Perforce PHP Object and Record Models...• Perforce PHP Object Model • Provides deep access to...
Transcript of Perforce PHP Object and Record Models...• Perforce PHP Object Model • Provides deep access to...
Perforce PHP Object and Record ModelsGeoff NicolSoftware Developer
Perforce PHP Object Model
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
MODELS
MODELS
MODELS
MODELS
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
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
CONNECTION SAMPLE
$connection = P4_Connection::factory( 'perforce:1666', 'user', 'client', null);
P4_Connection::setDefaultConnection($connection);
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}
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()
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
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
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();
Perforce CMSRecord Model
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
SIMPLE STATIC API
• store(<values>)• fetch(<id>)• fetchAll(<query>)• exists(<id>)• count(<query>)• remove(<id>)
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)
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
OBJECT MODEL
• Can instantiate record class• Provides in-memory data objects• get/setId()• get/setValues()• save()• delete()
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)
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()
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
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)
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
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
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
Questions ???