From: Michael Wallner Date: Mon, 21 Sep 2015 16:16:04 +0000 (+0200) Subject: phpdoc X-Git-Url: https://git.m6w6.name/?p=m6w6%2Fpq-gateway;a=commitdiff_plain;h=05a907a5cb7377e2ad7abfa21096e3630752b944;hp=d4d84fb9b85f0216bd611946d59054a606c71960 phpdoc --- diff --git a/lib/pq/Mapper/Map.php b/lib/pq/Mapper/Map.php index b63ba46..58e1e5d 100644 --- a/lib/pq/Mapper/Map.php +++ b/lib/pq/Mapper/Map.php @@ -5,15 +5,37 @@ namespace pq\Mapper; use pq\Gateway\Row; use pq\Gateway\Rowset; use pq\Gateway\Table; +use pq\Gateway\Table\Reference; use pq\Query\Expr; class Map implements MapInterface { + /** + * @var string + */ private $class; + + /** + * @var Table + */ private $gateway; + + /** + * @var ObjectManager + */ private $objects; + + /** + * @var PropertyInterface[] + */ private $properties; + /** + * Create a new object map definition + * @param string $class + * @param Table $gateway + * @param ...PropertyInterface $properties + */ function __construct($class, Table $gateway, PropertyInterface ...$properties) { $this->class = $class; $this->gateway = $gateway; @@ -24,31 +46,56 @@ class Map implements MapInterface $this->objects = new ObjectManager($this); } + /** + * Get the name of the mapped class + * @return string + */ function getClass() { return $this->class; } + /** + * Get the object manager + * @return ObjectManager + */ function getObjects() { return $this->objects; } /** + * Get the underlying table gateway * @return Table */ function getGateway() { return $this->gateway; } + /** + * Get the defined properties to map + * @return PropertyInterface[] + */ function getProperties() { return $this->properties; } + /** + * Add a property to map + * @param PropertyInterface $property + * @return Map + */ function addProperty(PropertyInterface $property) { $property->setContainer($this); $this->properties[] = $property; return $this; } + /** + * Get all child rows by foreign key + * @param Row $row + * @param string $refName + * @param array $objects + * @return Rowset + */ function allOf(Row $row, $refName, &$objects = null) { /* apply objectOf to populate the object cache */ return $this->gateway->of($row, $refName)->apply(function($row) use(&$objects) { @@ -56,6 +103,13 @@ class Map implements MapInterface }); } + /** + * Get the parent row by foreign key + * @param Row $row + * @param string $refName + * @param array $objects + * @return Rowset + */ function refOf(Row $row, $refName, &$objects = null) { $rid = []; $rel = $row->getTable()->getRelation($this->gateway->getName(), $refName); @@ -77,11 +131,22 @@ class Map implements MapInterface }); } + /** + * Get the table relation reference + * @param MapInterface $map + * @param string $refName + * @return Reference + */ function relOf(MapInterface $map, $refName) { return $map->getGateway()->getRelation( $this->gateway->getName(), $refName); } + /** + * Drain the deferred callback queue + * @param callable[] $deferred + * @param callable $exec + */ private function drain(array $deferred, callable $exec) { while ($deferred) { $cb = array_shift($deferred); @@ -91,6 +156,11 @@ class Map implements MapInterface } } + /** + * Map a row to an object + * @param Row $row + * @return object + */ function map(Row $row) { $deferred = []; $object = $this->objects->asObject($row); @@ -105,6 +175,11 @@ class Map implements MapInterface return $object; } + /** + * Map a rowset to an array of objects + * @param Rowset $rows + * @return object[] + */ function mapAll(Rowset $rows) { $objects = []; foreach ($rows as $row) { @@ -113,6 +188,10 @@ class Map implements MapInterface return $objects; } + /** + * Unmap on object + * @param object $object + */ function unmap($object) { $deferred = []; /* @var $row Row */ @@ -149,5 +228,4 @@ class Map implements MapInterface $row->update(); } } - -} \ No newline at end of file +} diff --git a/lib/pq/Mapper/MapInterface.php b/lib/pq/Mapper/MapInterface.php index 0e0db3a..8c95056 100644 --- a/lib/pq/Mapper/MapInterface.php +++ b/lib/pq/Mapper/MapInterface.php @@ -9,26 +9,31 @@ use pq\Gateway\Table; interface MapInterface { /** + * Get the mapped class' name * @return string */ function getClass(); /** + * The the underlying table gateway * @return Table */ function getGateway(); /** - * @return array of PropertyInterface instances + * Get the mapped properties + * @return PropertyInterface[] */ function getProperties(); /** + * Add a property to map * @param PropertyInterface $property */ function addProperty(PropertyInterface $property); /** + * Get all child rows by foreign key * @param Row $row * @param string $refName * @param array $objects @@ -37,6 +42,7 @@ interface MapInterface function allOf(Row $row, $refName, &$objects = null); /** + * Get the parent row by foreign key * @param Row $row * @param string $refName * @param array $objects @@ -45,25 +51,29 @@ interface MapInterface function refOf(Row $row, $refName, &$objects = null); /** + * Get the table relation reference * @param MapInterface $map origin * @param string $refName relations reference name - * @return array relation reference + * @return Table\Reference */ function relOf(MapInterface $map, $refName); /** + * Map a row to an object * @param Row $row * @return object */ function map(Row $row); /** + * Map a rowset to an array of objects * @param Rowset $rows - * @return array + * @return object[] */ function mapAll(Rowset $rows); /** + * Unmap on object * @param object $object * @return Row */ diff --git a/lib/pq/Mapper/Mapper.php b/lib/pq/Mapper/Mapper.php index 1c70f72..4a8f921 100644 --- a/lib/pq/Mapper/Mapper.php +++ b/lib/pq/Mapper/Mapper.php @@ -2,37 +2,56 @@ namespace pq\Mapper; +use pq\Mapper\Property\All; +use pq\Mapper\Property\Field; +use pq\Mapper\Property\Ref; +use ReflectionProperty; use UnexpectedValueException; class Mapper { + /** + * @var MapInterface[] + */ private $maps; + + /** + * @var ReflectionProperty[] + */ private $refp; /** - * @param \pq\Mapper\MapInterface $map - * @return \pq\Mapper\Mapper + * Register a mapping + * @param MapInterface $map + * @return Mapper */ function register(MapInterface $map) { $this->maps[$map->getClass()] = $map; return $this; } + /** + * Get a property reflector + * @param string $class + * @param string $prop + * @return ReflectionProperty + */ function getReflector($class, $prop) { if (is_object($class)) { $class = get_class($class); } $hash = "$class::$prop"; if (!isset($this->refp[$hash])) { - $this->refp[$hash] = new \ReflectionProperty($class, $prop); + $this->refp[$hash] = new ReflectionProperty($class, $prop); $this->refp[$hash]->setAccessible(true); } return $this->refp[$hash]; } /** + * Get the mapping of $class * @param string $class - * @return \pq\Mapper\MapInterface + * @return MapInterface * @throws UnexpectedValueException */ function mapOf($class) { @@ -49,35 +68,39 @@ class Mapper } /** + * Create a storage for $class * @param string $class - * @return \pq\Mapper\Storage + * @return Storage */ function createStorage($class) { return new Storage($this->mapOf($class)); } /** + * Create a simple field mapping * @param string $property * @param string $field - * @return \pq\Mapper\Property\Field + * @return Field */ function mapField($property, $field = null) { - return new Property\Field($this, $property, $field); + return new Field($this, $property, $field); } /** + * Create a child rows mapping by foreign key * @param string $property - * @return \pq\Mapper\Property\All + * @return All */ function mapAll($property) { - return new Property\All($this, $property); + return new All($this, $property); } /** + * Create a parent row mapping by foreign key * @param string $property - * @return \pq\Mapper\Property\Ref + * @return Ref */ function mapRef($property) { - return new Property\Ref($this, $property); + return new Ref($this, $property); } } diff --git a/lib/pq/Mapper/ObjectManager.php b/lib/pq/Mapper/ObjectManager.php index 557d494..0281904 100644 --- a/lib/pq/Mapper/ObjectManager.php +++ b/lib/pq/Mapper/ObjectManager.php @@ -8,19 +8,47 @@ use pq\Gateway\Row; class ObjectManager { + /** + * @var MapInterface + */ private $map; + + /** + * @var object[] + */ private $obj = []; + + /** + * @var Row[] + */ private $row = []; + /** + * Create a new ObjectManager for a mapping + * @param MapInterface $map + */ function __construct(MapInterface $map) { $this->map = $map; } + /** + * Reset all managed objects + */ function reset() { $this->obj = []; $this->row = []; } + /** + * Get the serialized row identity + * + * When $check is true, the identity will only be serialized if all columns + * of the primary key are set. + * + * @param Row $row + * @param bool $check + * @return string|false serialized row id or false on failure + */ function rowId(Row $row, $check = false) { try { $identity = $row->getIdentity(); @@ -30,10 +58,20 @@ class ObjectManager return $this->serializeRowId($identity, $check); } + /** + * Get an object's identity + * @param object $object + * @return string + */ function objectId($object) { return spl_object_hash($object); } + /** + * Extract a row's identity from a mapped object + * @param object $object + * @return string serialized row identity + */ function extractRowId($object) { $id = []; foreach ($this->map->getGateway()->getIdentity() as $col) { @@ -46,6 +84,12 @@ class ObjectManager return $this->serializeRowId($id, true); } + /** + * Serialize a row's identity + * @param mixed $identity + * @param bool $check + * @return string|false the serialized row identity or false on failure + */ function serializeRowId($identity, $check = false) { if (is_scalar($identity)) { return $identity; @@ -65,10 +109,20 @@ class ObjectManager return json_encode($identity); } + /** + * Check whether a mapped object is already cached in the manager + * @param string $row_id + * @return bool + */ function hasObject($row_id) { return isset($this->obj[$row_id]); } + /** + * Create a mapped object from $row + * @param Row $row + * @return object + */ function createObject(Row $row) { $rid = $this->rowId($row); $cls = $this->map->getClass(); @@ -79,15 +133,30 @@ class ObjectManager return $obj; } + /** + * Forget the mapped object of $row + * @param Row $row + */ function resetObject(Row $row) { unset($this->obj[$this->rowId($row)]); } + /** + * Get the mapped object of $row + * @param Row $row + * @return object + */ function getObject(Row $row) { $id = $this->rowId($row); return $this->getObjectById($id); } + /** + * Get the mapped object of $row + * @param string $row_id + * @return object + * @throws BadMethodCallException + */ function getObjectById($row_id) { if (!$this->hasObject($row_id)) { throw new BadMethodCallException("Object of row with id $row_id does not exist"); @@ -95,16 +164,31 @@ class ObjectManager return $this->obj[$row_id]; } + /** + * Check for a mapped object of $row, and create if necessary + * @param Row $row + * @return object + */ function asObject(Row $row){ return $this->hasObject($this->rowId($row)) ? $this->getObject($row) : $this->createObject($row); } + /** + * Check whether a row for a mapped object exists + * @param string $obj_id + * @return Row + */ function hasRow($obj_id) { return isset($this->row[$obj_id]); } + /** + * Initialize a Row from a mapped object + * @param object $object + * @return Row + */ function createRow($object) { $oid = $this->objectId($object); $row = new Row($this->map->getGateway()); @@ -112,10 +196,20 @@ class ObjectManager return $row; } + /** + * Forget about a row of a mapped object + * @param object $object + */ function resetRow($object) { unset($this->row [$this->objectId($object)]); } - + + /** + * Get the row of a mapped object + * @param object $object + * @return Row + * @throws BadMethodCallException + */ function getRow($object) { $id = $this->objectId($object); @@ -125,9 +219,14 @@ class ObjectManager return $this->row[$id]; } + /** + * Check for a row of a mapped object, create from object if neccessary + * @param object $object + * @return Row + */ function asRow($object) { return $this->hasRow($this->objectId($object)) ? $this->getRow($object) : $this->createRow($object); } -} \ No newline at end of file +} diff --git a/lib/pq/Mapper/Property.php b/lib/pq/Mapper/Property.php index ba4495b..7d87ab3 100644 --- a/lib/pq/Mapper/Property.php +++ b/lib/pq/Mapper/Property.php @@ -4,43 +4,92 @@ namespace pq\Mapper; trait Property { + /** + * + * @var Mapper + */ private $mapper; + + /** + * @var string + */ private $field; + + /** + * @var string + */ private $property; + /** + * Set the containing map + * @param MapInterface $container + * @return Property + */ function setContainer(MapInterface $container) { $this->container = $container; + return $this; } + /** + * Get the containing map + * @return MapInterface + */ function getContainer() { return $this->container; } + /** + * Get the property name + * @return string + */ function getProperty() { return $this->property; } + /** + * Check whether this Property defines $property + * @param string $property + * @return bool + */ function defines($property) { return $this->property === $property; } + /** + * Check whether this property exposes $field + * @param string $field + * @return bool + */ function exposes($field) { return $this->field === $field; } + /** + * Set the value of the mapped property + * @param object $object + * @param mixed $value + */ function assign($object, $value) { $this->mapper ->getReflector($object, $this->property) ->setValue($object, $value); } + /** + * Get the value of the mapped property + * @param object $object + * @return mixed + */ function extract($object) { return $this->mapper ->getReflector($object, $this->property) ->getValue($object); } + /** + * @ignore + */ function __toString() { return sprintf("%s: %s(%s)", get_class($this), $this->property, $this->field?:"NULL"); } -} \ No newline at end of file +} diff --git a/lib/pq/Mapper/Property/All.php b/lib/pq/Mapper/Property/All.php index 0f45174..49fb0a6 100644 --- a/lib/pq/Mapper/Property/All.php +++ b/lib/pq/Mapper/Property/All.php @@ -11,12 +11,22 @@ use UnexpectedValueException; class All implements RefPropertyInterface { use RefProperty; - + + /** + * Create a child rows mapping + * @param Mapper $mapper + * @param string $property + */ function __construct(Mapper $mapper, $property) { $this->mapper = $mapper; $this->property = $property; } - + + /** + * Read the child objects + * @param Row $row + * @param object $objectToUpdate + */ function read(Row $row, $objectToUpdate) { $val = $this->extract($objectToUpdate); if (!isset($val)) { @@ -27,6 +37,12 @@ class All implements RefPropertyInterface } } + /** + * Write the child rows + * @param object $object + * @param Row $rowToUpdate + * @return callable deferred callback + */ function write($object, Row $rowToUpdate) { $property = $this->findRefProperty($object); $map = $this->mapper->mapOf($this->refClass); @@ -41,6 +57,12 @@ class All implements RefPropertyInterface }; } + /** + * Find the referring property that references $object on our foreign key + * @param object $object + * @return RefPropertyInterface[] + * @throws UnexpectedValueException + */ private function findRefProperty($object) { $map = $this->mapper->mapOf($this->refClass); $property = array_filter($map->getProperties(), function($property) use($object) { @@ -57,4 +79,4 @@ class All implements RefPropertyInterface } return current($property); } -} \ No newline at end of file +} diff --git a/lib/pq/Mapper/Property/Field.php b/lib/pq/Mapper/Property/Field.php index 7a57741..78c500b 100644 --- a/lib/pq/Mapper/Property/Field.php +++ b/lib/pq/Mapper/Property/Field.php @@ -2,8 +2,8 @@ namespace pq\Mapper\Property; +use pq\Gateway\Cell; use pq\Gateway\Row; - use pq\Mapper\Mapper; use pq\Mapper\Property; use pq\Mapper\PropertyInterface; @@ -12,18 +12,34 @@ class Field implements PropertyInterface { use Property; + /** + * Create a simple field mapping + * @param Mapper $mapper + * @param string $property + * @param string $field + */ function __construct(Mapper $mapper, $property, $field = null) { $this->mapper = $mapper; $this->property = $property; $this->field = $field ?: $property; } + /** + * Read property value + * @param Row $row + * @param object $objectToUpdate + */ function read(Row $row, $objectToUpdate) { - /* @var $val \pq\Gateway\Cell */ + /* @var $val Cell */ $val = $row->{$this->field}; $this->assign($objectToUpdate, $val->get()); } + /** + * Write property value + * @param object $object + * @param Row $rowToUpdate + */ function write($object, Row $rowToUpdate) { $val = $this->extract($object); $rowToUpdate->{$this->field} = $val; diff --git a/lib/pq/Mapper/Property/Ref.php b/lib/pq/Mapper/Property/Ref.php index 84f39f4..01489d9 100644 --- a/lib/pq/Mapper/Property/Ref.php +++ b/lib/pq/Mapper/Property/Ref.php @@ -4,6 +4,7 @@ namespace pq\Mapper\Property; use pq\Gateway\Row; use pq\Mapper\Mapper; +use pq\Mapper\PropertyInterface; use pq\Mapper\RefProperty; use pq\Mapper\RefPropertyInterface; use UnexpectedValueException; @@ -11,12 +12,22 @@ use UnexpectedValueException; class Ref implements RefPropertyInterface { use RefProperty; - + + /** + * Create a parent row mapping + * @param Mapper $mapper + * @param string $property + */ function __construct(Mapper $mapper, $property) { $this->mapper = $mapper; $this->property = $property; } + /** + * Read the parent object + * @param Row $row + * @param object $objectToUpdate + */ function read(Row $row, $objectToUpdate) { $val = $this->extract($objectToUpdate); if (!isset($val)) { @@ -27,6 +38,12 @@ class Ref implements RefPropertyInterface } } + /** + * Write the parent row's foreign key + * @param object $object + * @param Row $rowToUpdate + * @throws UnexpectedValueException + */ function write($object, Row $rowToUpdate) { $map = $this->mapper->mapOf($this->refClass); $ref = $this->extract($object); @@ -45,6 +62,11 @@ class Ref implements RefPropertyInterface } } + /** + * Find the property exposing $col + * @param string $col + * @return PropertyInterface[] + */ private function findFieldProperty($col) { $map = $this->mapper->mapOf($this->refClass); return array_filter($map->getProperties(), function($property) use($col) { diff --git a/lib/pq/Mapper/PropertyInterface.php b/lib/pq/Mapper/PropertyInterface.php index da6ccd3..b53e2b8 100644 --- a/lib/pq/Mapper/PropertyInterface.php +++ b/lib/pq/Mapper/PropertyInterface.php @@ -6,18 +6,66 @@ use pq\Gateway\Row; interface PropertyInterface { + /** + * Write the value for the property from $object into the row to update + * @param object $object + * @param Row $rowToUpdate + * @return null|callable eventual deferred callback + */ function write($object, Row $rowToUpdate); + + /** + * Read the value for the property from $row into the mapped object + * @param Row $row + * @param object $objectToUpdate + * @return null|callable eventual deferred callback + */ function read(Row $row, $objectToUpdate); + /** + * Set the value of the mapped property + * @param object $object + * @param mixed $value + */ function assign($object, $value); + + /** + * Get the value of the mapped property + * @param object $object + * @return mixed + */ function extract($object); + /** + * Get the property name + * @return string + */ function getProperty(); + /** + * Get the containing map + * @return MapInterface + */ function getContainer(); + + /** + * Set the containing map + * @param MapInterface $container + * @return Property + */ function setContainer(MapInterface $container); + /** + * Check whether this Property defines $property + * @param string $property + * @return bool + */ function defines($property); - function exposes($field); + /** + * Check whether this property exposes $field + * @param string $field + * @return bool + */ + function exposes($field); } diff --git a/lib/pq/Mapper/RefProperty.php b/lib/pq/Mapper/RefProperty.php index d7c6c6f..50b6288 100644 --- a/lib/pq/Mapper/RefProperty.php +++ b/lib/pq/Mapper/RefProperty.php @@ -6,25 +6,53 @@ trait RefProperty { use Property; + /** + * The referred class + * @var string + */ private $refClass; + + /** + * The foreign key name + * @var string + */ private $refName; + /** + * Define the referred class + * @param string $class + * @return RefPropertyInterface + */ function to($class) { $this->refClass = $class; return $this; } + /** + * Check whether this mapping refers to $class + * @param string $class + * @return bool + */ function references($class) { return $this->refClass === (is_object($class) ? get_class($class) : $class); } + /** + * Define the foreign key name as defined by pq\Gateway\Table\Reference + * @param string $ref + * @return RefPropertyInterface + */ function by($ref) { $this->refName = $ref; return $this; } + /** + * Check whether this mapping referes to a foreign key + * @param string $ref + * @return bool + */ function on($ref) { return $this->refName === $ref; } - } diff --git a/lib/pq/Mapper/RefPropertyInterface.php b/lib/pq/Mapper/RefPropertyInterface.php index 5fae13a..f9b1ee5 100644 --- a/lib/pq/Mapper/RefPropertyInterface.php +++ b/lib/pq/Mapper/RefPropertyInterface.php @@ -5,22 +5,28 @@ namespace pq\Mapper; interface RefPropertyInterface extends PropertyInterface { /** + * Define the referred class * @param string $class + * @return RefPropertyInterface */ function to($class); /** + * Check whether this mapping refers to $class * @param string $class * @return bool */ function references($class); /** + * Define the foreign key name as defined by pq\Gateway\Table\Reference * @param string $ref + * @return RefPropertyInterface */ function by($ref); /** + * Check whether this mapping referes to a foreign key * @param string $ref * @return bool */ diff --git a/lib/pq/Mapper/Storage.php b/lib/pq/Mapper/Storage.php index 8e0fcb4..8016ef8 100644 --- a/lib/pq/Mapper/Storage.php +++ b/lib/pq/Mapper/Storage.php @@ -2,39 +2,61 @@ namespace pq\Mapper; +use pq\Gateway\Table; + class Storage implements StorageInterface { /** - * - * @var pq\Mapper\MapInterface + * The mapping of this storage + * @var MapInterface */ - private $map; + var $map; /** - * @var \pq\Gateway\Table + * The underlying table gateway + * @var Table */ private $gateway; - + + /** + * Create a storage for $map + * @param MapInterface $map + */ function __construct(MapInterface $map) { $this->map = $map; $this->gateway = $map->getGateway(); } - + + /** + * Find + * @param array $where + * @param string $order + * @param int $limit + * @param int $offset + * @return object[] + */ function find($where = [], $order = null, $limit = null, $offset = null) { /* @var pq\Gateway\Rowset $rowset */ $rowset = $this->gateway->find($where, $order, $limit, $offset); return $this->map->mapAll($rowset); } - + + /** + * Delete + * @param object $object + */ function delete($object) { $cache = $this->map->getObjects(); $row = $cache->asRow($object)->delete(); $cache->resetObject($row); $cache->resetRow($object); } - + + /** + * Save + * @param object $object + */ function save($object) { $this->map->unmap($object); } - -} \ No newline at end of file +} diff --git a/lib/pq/Mapper/StorageInterface.php b/lib/pq/Mapper/StorageInterface.php index 188318a..bb5c94a 100644 --- a/lib/pq/Mapper/StorageInterface.php +++ b/lib/pq/Mapper/StorageInterface.php @@ -4,7 +4,25 @@ namespace pq\Mapper; interface StorageInterface { - function find($where, $order = null, $limit = null, $offset = null); + /** + * Find + * @param array $where + * @param string $order + * @param int $limit + * @param int $offset + * @return object[] + */ + function find($where = [], $order = null, $limit = null, $offset = null); + + /** + * Delete + * @param object $object + */ function delete($object); + + /** + * Save + * @param object $object + */ function save($object); }