|
Perforce Chronicle 2012.2/486814
API Documentation
|
Storage for custom urls. More...
Public Member Functions | |
| delete ($description=null) | |
| Extends delete to also remove the param-lookup record. | |
| getParamRecord () | |
| Get a copy of the associated param record (not a reference). | |
| getParams () | |
| Get the url route parameters associated with this path. | |
| getPath () | |
| Get the path of this url (alias for getId). | |
| save ($description=null, $options=null) | |
| Extends save to write a param lookup record for each url record. | |
| setId ($id) | |
| Set the id of this record (aka. | |
| setParams ($params) | |
| Set url route parameters to associate with this url path. | |
| setPath ($path) | |
| Set the path of this url (alias for setId). | |
Static Public Member Functions | |
| static | fetchByContent ($content, $query=null, P4Cms_Record_Adapter $adapter=null) |
| Get a url record by content id. | |
| static | fetchByParams (array $params, $query=null, P4Cms_Record_Adapter $adapter=null) |
| Get a url record by route parameters. | |
| static | getContentRouteParams ($content) |
| Get route parameters to view a specific content entry. | |
| static | makeParamId (array $params) |
| Generate the lookup record id for a given set of url route parameters. | |
| static | normalizePath ($path) |
| Normalize a url path component. | |
Protected Member Functions | |
| _encodeId ($id) | |
| Encode id for storage - extended to normalize path. | |
Static Protected Member Functions | |
| static | _makeParamHash ($params) |
| Make a hash (md5) for a given set of url route params. | |
Static Protected Attributes | |
| static | $_encodeIds = true |
| Optionally, bin2hex encode identifiers when converting to/from depot filespecs to permit non-standard characters. | |
| static | $_idField = null |
| All records should have an id field. | |
| static | $_lookupPath = 'urls/by-params' |
| static | $_storageSubPath = 'urls/by-path' |
| Specifies the sub-path to use for storage of records. | |
Storage for custom urls.
Each entry maps an arbitrary url path to a set of route parameters (e.g. module/controller/action/id/etc.).
The id of each record is the url path. The url path is always normalized to a consistent level of url encoding (and hex encoded for storage). This makes lookups by path quick. To speed up access by parameters a param lookup record is written every time a custom url is saved. Similarly, the lookup record is removed any time a custom url is deleted. Lookups by parameters will only match if the params are identical to those in the primary url record.
| Url_Model_Url::_encodeId | ( | $ | id | ) | [protected] |
Encode id for storage - extended to normalize path.
| string | $id | the id to encode. |
Reimplemented from P4Cms_Record.
{
return parent::_encodeId(static::normalizePath($id));
}
| static Url_Model_Url::_makeParamHash | ( | $ | params | ) | [static, protected] |
Make a hash (md5) for a given set of url route params.
The params are sorted to ensure the id is consistently generated regardless of the input order.
| array | $params | the params to generate a hash for. |
{
ksort($params);
return md5(serialize($params));
}
| Url_Model_Url::delete | ( | $ | description = null | ) |
Extends delete to also remove the param-lookup record.
| string | $description | optional - a description of the change. |
Reimplemented from P4Cms_Record.
{
$description = $description ?: $this->_generateSubmitDescription();
// begin a batch if we're not already in one.
$adapter = $this->getAdapter();
$batch = !$adapter->inBatch()
? $adapter->beginBatch($description)
: false;
// wrap in a try/catch so we can cleanup if something goes wrong.
try {
// standard delete behavior.
parent::delete($description);
// remove our param lookup record.
P4Cms_Record::remove(static::makeParamId($this->getParams()), $adapter);
} catch (Exception $e) {
if ($batch) {
$adapter->revertBatch();
}
throw $e;
}
// commit the batch.
if ($batch) {
$adapter->commitBatch(null);
}
return $this;
}
| static Url_Model_Url::fetchByContent | ( | $ | content, |
| $ | query = null, |
||
| P4Cms_Record_Adapter $ | adapter = null |
||
| ) | [static] |
Get a url record by content id.
| string | P4Cms_Content | $content | the content to get a url for. |
| P4Cms_Record_Query | array | null | $query | optional - query options to augment result. |
| P4Cms_Record_Adapter | $adapter | optional - storage adapter to use. |
{
return static::fetchByParams(
static::getContentRouteParams($content),
$query,
$adapter
);
}
| static Url_Model_Url::fetchByParams | ( | array $ | params, |
| $ | query = null, |
||
| P4Cms_Record_Adapter $ | adapter = null |
||
| ) | [static] |
Get a url record by route parameters.
The route parameters must exactly match those specified when the primary url record was saved.
| array | $params | the route parameters to lookup. |
| P4Cms_Record_Query | array | null | $query | optional - query options to augment result. |
| P4Cms_Record_Adapter | $adapter | optional - storage adapter to use. |
| P4Cms_Record_NotFoundException | if the requested record can't be found. |
{
// check param lookup table for a reference to a url record.
$lookup = P4Cms_Record::fetch(static::makeParamId($params), $query, $adapter);
// if we're still here, we found one - the id of the url record
// is held in the path field, use that to fetch the record.
$record = static::fetch($lookup->getValue('path'), $query, $adapter);
// verify params match - due to the structure of the data, it is
// technically possible for two lookup records to point to the same
// primary record, ensuring the params match protects against this.
if ($record->getParams() != $params) {
throw new P4Cms_Record_NotFoundException(
"Cannot find url record with matching parameters."
);
}
return $record;
}
| static Url_Model_Url::getContentRouteParams | ( | $ | content | ) | [static] |
Get route parameters to view a specific content entry.
Saves us from having to re-iterate the route params everywhere.
| string | P4Cms_Content | $content | the content to get route params for. |
{
$content = $content instanceof P4Cms_Content ? $content->getId() : $content;
// verify content is now a string id.
if (!is_string($content)) {
throw new InvalidArgumentException(
"Cannot fetch url record. Content must be a content object or string id."
);
}
return array(
'module' => 'content',
'controller' => 'index',
'action' => 'view',
'id' => $content
);
}
| Url_Model_Url::getParamRecord | ( | ) |
Get a copy of the associated param record (not a reference).
| P4Cms_Record_NotFoundException | if no associated record exists in storage. |
{
return P4Cms_Record::fetch(
static::makeParamId($this->getParams()),
null,
$this->getAdapter()
);
}
| Url_Model_Url::getParams | ( | ) |
Get the url route parameters associated with this path.
Effectively an alias to getValues().
{
return $this->getValues();
}
| Url_Model_Url::getPath | ( | ) |
Get the path of this url (alias for getId).
{
return $this->getId();
}
| static Url_Model_Url::makeParamId | ( | array $ | params | ) | [static] |
Generate the lookup record id for a given set of url route parameters.
The id is a combination of the param lookup storage path and the param hash.
| array | $params | the params to generate an id for. |
{
$hash = static::_makeParamHash($params);
return static::$_lookupPath . '/' . $hash;
}
| static Url_Model_Url::normalizePath | ( | $ | path | ) | [static] |
Normalize a url path component.
See Url_Filter_UrlPath for details.
| string | null | $path | the url path component to filter. |
| InvalidArgumentException | if given value is not a string or null. |
{
// null in, null out.
if (is_null($path)) {
return null;
}
$filter = new Url_Filter_UrlPath;
return $filter->filter($path);
}
| Url_Model_Url::save | ( | $ | description = null, |
| $ | options = null |
||
| ) |
Extends save to write a param lookup record for each url record.
Also, verifies path has been set (that is the whole point).
| string | $description | optional - a description of the change. |
| null | string | array | $options | optional - passing the SAVE_THROW_CONFLICTS flag will cause exceptions on conflict; default behaviour is to crush any conflicts. Note this flag has no effect in batches. |
| Url_Exception | if no path (id) has been set. |
Reimplemented from P4Cms_Record.
{
$description = $description ?: $this->_generateSubmitDescription();
// ensure we have a path/id.
if (!$this->getPath()) {
throw new Url_Exception("Cannot save url record without a path.");
}
// begin a batch if we're not already in one.
$adapter = $this->getAdapter();
$batch = !$adapter->inBatch()
? $adapter->beginBatch($description)
: false;
// wrap in a try/catch so we can cleanup if something goes wrong.
try {
// standard save behavior.
parent::save($description);
// save our param lookup record (for quick lookup by params)
P4Cms_Record::store(
array(
'id' => static::makeParamId($this->getParams()),
'path' => $this->getId()
),
$adapter
);
} catch (Exception $e) {
if ($batch) {
$adapter->revertBatch();
}
throw $e;
}
// commit the batch.
if ($batch) {
$adapter->commitBatch(null, $options);
}
return $this;
}
| Url_Model_Url::setId | ( | $ | id | ) |
Set the id of this record (aka.
the url path). Extended to always normalize the path encoding.
| string | null | $id | the identifier of this record. |
Reimplemented from P4Cms_Record.
{
return parent::setId(static::normalizePath($id));
}
| Url_Model_Url::setParams | ( | $ | params | ) |
Set url route parameters to associate with this url path.
Any existing parameters will be cleared.
| array | null | $params | array of url route parameters to set. |
{
$this->_values = array();
return $this->setValues($params);
}
| Url_Model_Url::setPath | ( | $ | path | ) |
Set the path of this url (alias for setId).
| string | null | $path | the path of the url. |
{
return $this->setId($path);
}
Url_Model_Url::$_encodeIds = true [static, protected] |
Optionally, bin2hex encode identifiers when converting to/from depot filespecs to permit non-standard characters.
Reimplemented from P4Cms_Record.
Url_Model_Url::$_idField = null [static, protected] |
All records should have an id field.
Reimplemented from P4Cms_Record.
Url_Model_Url::$_lookupPath = 'urls/by-params' [static, protected] |
Url_Model_Url::$_storageSubPath = 'urls/by-path' [static, protected] |
Specifies the sub-path to use for storage of records.
This is used in combination with the records path (provided by the storage adapter) to construct the full storage path. The implementing class MUST set this property.
Reimplemented from P4Cms_Record.