The Perforce Web Content Management System development team, lacking a pre-existing solution in PHP, designed and implemented their own object model and record layer to ease the interaction of the system with the Perforce Server. This session will focus on how users can access files in Perforce via a simple CRUD API, the subsystems exposed, and their usage.

1. Perforce PHP Object and
Record Models
Geoff Nicol
Software Developer

2. Perforce PHP Object Model

3. Overview
• Abstract perforce operations
• Do a lot of the parsing and assembly to avoid string bashing elsewhere
• Create a more PHP natural layer
• Wrap multiple connection types
• Provide a reliable interface
• Creates a foundation for PHP Record Model

4. MODELS

5. MODELS

6. MODELS

7. MODELS

8. SPEC OUTPUT SAMPLE
p4 changes -m1
... change 318652
... time 1305914360
... user gnicol
... client gnicol
... status submitted
... changeType public
... path //depot/main/application/...
... desc Sed ut perspiciatis und
p4 change -o 318652
... Change 318652
... Date 2011/05/20 10:59:20
... Client gnicol
... User gnicol
... Status submitted
... Description Sed ut perspiciatis unde omnis iste natus
error sit voluptatem.
Accusantium doloremque laudantium.
... Type public

9. CONNECTION HANDLING
• Connection Abstract defines base capabilities
• Concrete wrappers for CLI and Native Extension
• Static factory method does type selection
• Supports concept of setting ‘default’ connection
• Connected Abstract
• Implements [get/set/has/clear]Connection
• Provides static getDefaultConnection to allow per-model defaults

10. CONNECTION SAMPLE
$connection = P4_Connection::factory(
'perforce:1666',
'user',
'client',
null
);
P4_Connection::setDefaultConnection($connection);

11. SPEC SAMPLE
// Assume default connection setup as per previous example
$job = new P4_Job();
$job->setDescription('test')->save();
// Or use a manual connection
$job = new P4_Job(
P4_Connection::factory('other:1666', 'joe')
);
$job->setValue('Description', 'test2')->save();
// will contain a partially populated version
$jobs = P4_Job::fetchAll(
array(P4_Job::FETCH_BY_FILTER => 'test')
);
foreach($jobs as $job) {
echo $job->getId(); // Pulled from partial population
echo ': ' . $job->getDescription(); // Will lazy load
}

12. P4_File
• Wraps numerous perforce commands (fstat, print, attribute, etc.)
• Allows users to limit files via a Query API we provide
• Limit results based on path(s)
• Specify sorting options
• Paginate results: max rows, row offset
• Exposes our Filter API to further limit results
• Programmatic interface to fstat -F <expr>
• Supports literal and regex matches
• Conditions can be AND’d, OR’d together
• Supports sub-filters
• Casts to fstat -F <expr> via toString()

13. FILE SAMPLE
$file = new P4_File;
$file->setFilespec('//depot/small.txt')
->open()
->setLocalContents('A small file.')
->setAttribute('foo', 'small')
->submit('Add a small file.');
$file->edit()
->setLocalContents('An edited small file.')
->submit('Edit a small file');
echo P4_File::fetch('//depot/small.txt')
->getDepotContents();
----- Output ------------------------------------------
Edit a small file

14. SUGAR
• Pass strings or objects when passing parameters like user, group, etc.
• Spec word-lists are returned as associative arrays
• Mutators accept hashes or strings as input
• A fluent interface is supported wherever possible
• Iterator provide convenience methods such as Invoke, Filter, Search, Sort

15. SUGAR EXAMPLES
// Pass in object or string, where appropriate
$group = new P4_Group;
$user = P4_User::fetch('Bob');
$group->setId('test')
->addUser($user)
->addUser('joe')
->save();
// Pass in string or hash, where appropriate
$triggers = P4_Triggers::fetch();
$values = $triggers->getTriggers();
$values[] = 'test-trigger form-in //... /path/script.sh';
$values[] = array(
'name' => 'test2',
'type' => 'form-out',
'path' => '//...',
'command' => '/path/otherScript.sh'
);
$triggers->setTriggers($values)->save();

16. Perforce CMS
Record Model

17. Overview
• Storing data in perforce can be hard, this layer should make it easy.
• Provide a natural CRUD interface more in line with Active Record
• Provide features such as lazy loading, fluent interface, etc.
• Has the option of extension
• Supports several modes of operation
• Static
• Object
• Extended Object

18. SIMPLE STATIC API
• store(<values>)
• fetch(<id>)
• fetchAll(<query>)
• exists(<id>)
• count(<query>)
• remove(<id>)

19. USING THE STATIC API
$record = P4Cms_Record::store(
array(
'firstName' => 'Don',
'lastName' => 'Draper’
)
);
print_r($record->getValues());
----- Output ------------------------------------------
Array(
[id] => 1
[firstName] => Don
[lastName] => Draper
)

20. STORAGE LOCATION
<storage path> / <storage sub-path> / <ID derived file name>
• Storage Path is provided by the Record Adapter
• We support a default adapter concept
• Storage Sub-Path is, optionally, provided by the Record Model
• ID is based on Record ID

21. OBJECT MODEL
• Can instantiate record class
• Provides in-memory data objects
• get/setId()
• get/setValues()
• save()
• delete()

22. USING THE OBJECT MODEL
$peg = new P4Cms_Record;
$peg->setValue('firstName', 'Peggy')
->setValue('lastName', 'Olson')
->save();
print_r($peg->getValues());
----- Output ------------------------------------------
Array(
[id] => 2
[firstName] => Peggy
[lastName] => Olson
)

23. EXTENDING THE OBJECT MODEL
• Why extend?
• Specify a storage sub-path
• Define defaults, known fields, id-field, file-field
• Define custom field accessors, mutators
• Provide access to related records
• e.g. $person->getFriends()

24. OTHER FEATURES
• Lazy-load
• fetch(<id>) defers populate until getValue()
• IDs & Auto-increment
• IDs can be strings e.g. ‘path/to/foo.bar’
• If no ID is given, store() makes one
• Query and Filter APIs extended from Object layer
• Batches
• Put modified records in a pending change
• Can be committed or reverted
• Faster, atomic

25. USING THE FILTER API
$names = array('Pete', 'Betty', 'Joan', 'Roger');
foreach ($names as $name) {
Person::store(array('firstName' => $name));
}
$filter = new P4Cms_Record_Filter;
$filter->add('firstName', array('Betty', 'Joan'));
$ladies = Person::fetchAll(
new P4Cms_Record_Query(array('filter' => $filter))
);
print_r($ladies->invoke('getValue', array('firstName'));
----- Output ------------------------------------------
Array(
[0] => Betty
[1] => Joan
)

26. USING BATCHES
$people = Person::fetchAll();
$adapter = P4Cms_Record::getDefaultAdapter();
$adapter->beginBatch('Bulk Update');
$people->invoke('setValue', array('fictional', true));
$people->invoke('save');
$adapter->commitBatch();
// use the P4 layer to verify batching occured
$changes = P4_Change::fetchAll(array('maximum' => 1));
print count($changes->current()->getFiles());
----- Output ------------------------------------------
6

27. HOW DOES IT WORK?
• Record ‘Adapter’ hold connection object, specifies storage path, manages
batches
• Record IDs map to filenames
• Values map to attributes
• Query API leans heavily on p4 fstat
• Uses our Perforce PHP Object Model

28. CONCLUSION
• Perforce PHP Object Model
• Provides deep access to perforce functionality
• Removes the need to bash strings and spec forms manually
• Provides a more consistent and fully detailed view of objects
• Perforce PHP Record Model
• Provides a more ActiveRecord style interface to Perforce
• Can be used in conjunction with Object Model

29. Questions ???