RetailCRM-Mirror/doctrine2
1
0
Fork 0
mirror of synced 2024-12-05 03:06:05 +03:00
Code Issues Projects Releases Wiki Activity

CS/Doc Fixes

Browse Source
This commit is contained in:
fabios 2013-12-02 16:56:16 -05:00
parent 71903c28a8
commit 0a66a2bc09
17 changed files with 138 additions and 324 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

335
docs/en/reference/second-level-cache.rst
View File

@ -71,7 +71,7 @@ A query region might be something like :
Cache Regions
-------------
``Doctrine\ORM\Cache\Region\DefaultRegion`` Its the default implementation.
``Doctrine\ORM\Cache\Region\DefaultRegion`` It's the default implementation.
A simplest cache region compatible with all doctrine-cache drivers but does not support locking.
``Doctrine\ORM\Cache\Region`` and ``Doctrine\ORM\Cache\ConcurrentRegion``
@ -91,59 +91,7 @@ Defines a contract for accessing a particular region.
Defines a contract for accessing a particular cache region.
.. code-block:: php
<?php
interface Region
{
/**
* Retrieve the name of this region.
*
* @return string The region name
*/
public function getName();
/**
* Determine whether this region contains data for the given key.
*
* @param \Doctrine\ORM\Cache\CacheKey $key The cache key
*
* @return boolean
*/
public function contains(CacheKey $key);
/**
* Get an item from the cache.
*
* @param \Doctrine\ORM\Cache\CacheKey $key The key of the item to be retrieved.
*
* @return \Doctrine\ORM\Cache\CacheEntry|null The cached entry or NULL
*/
public function get(CacheKey $key);
/**
* Put an item into the cache.
*
* @param \Doctrine\ORM\Cache\CacheKey $key The key under which to cache the item.
* @param \Doctrine\ORM\Cache\CacheEntry $entry The entry to cache.
* @param \Doctrine\ORM\Cache\Lock $lock The lock previously obtained.
*/
public function put(CacheKey $key, CacheEntry $entry, Lock $lock = null);
/**
* Remove an item from the cache.
*
* @param \Doctrine\ORM\Cache\CacheKey $key The key under which to cache the item.
*/
public function evict(CacheKey $key);
/**
* Remove all contents of this particular cache region.
*/
public function evictAll();
}
`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.Region.html/>`_.
Concurrent cache region
~~~~~~~~~~~~~~~~~~~~~~~
@ -157,29 +105,7 @@ If you want to use an ``READ_WRITE`` cache, you should consider providing your o
Defines contract for concurrently managed data region.
.. code-block:: php
<?php
interface ConcurrentRegion extends Region
{
/**
* Attempts to read lock the mapping for the given key.
*
* @param \Doctrine\ORM\Cache\CacheKey $key The key of the item to lock.
*
* @return \Doctrine\ORM\Cache\Lock A lock instance or NULL if the lock already exists.
*/
public function lock(CacheKey $key);
/**
* Attempts to read unlock the mapping for the given key.
*
* @param \Doctrine\ORM\Cache\CacheKey $key The key of the item to unlock.
* @param \Doctrine\ORM\Cache\Lock $lock The lock previously obtained from readLock
*/
public function unlock(CacheKey $key, Lock $lock);
}
`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.ConcurrentRegion.html/>`_.
Cache region
~~~~~~~~~~~~
@ -188,21 +114,7 @@ Cache region
Tracks the timestamps of the most recent updates to particular entity.
.. code-block:: php
<?php
interface TimestampRegion extends Region
{
/**
* Update an specific key into the cache region.
*
* @param \Doctrine\ORM\Cache\CacheKey $key The key of the item to update the timestamp.
*
* @throws \Doctrine\ORM\Cache\LockException Indicates a problem accessing the region.
*/
public function update(CacheKey $key);
}
`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.TimestampRegion.html/>`_.
.. _reference-second-level-cache-mode:
@ -218,7 +130,7 @@ Caching mode
* ``NONSTRICT_READ_WRITE``
* Read Write Cache doesn’t employ any locks but can do reads, inserts , updates and deletes.
* Read Write Cache doesn’t employ any locks but can do reads, inserts, updates and deletes.
* Good if the application needs to update data rarely.
@ -292,80 +204,7 @@ It allows you to provide a specific implementation of the following components :
* ``EntityHydrator`` Transform an entity into a cache entry and cache entry into entities
* ``CollectionHydrator`` Transform a collection into a cache entry and cache entry into collection
.. code-block:: php
<?php
interface CacheFactory
{
/**
* Build an entity persister for the given entity metadata.
*
* @param \Doctrine\ORM\EntityManagerInterface $em The entity manager
* @param \Doctrine\ORM\Persisters\EntityPersister $persister The entity persister
* @param \Doctrine\ORM\Mapping\ClassMetadata $metadata The entity metadata
*
* @return \Doctrine\ORM\Cache\Persister\CachedEntityPersister
*/
public function buildCachedEntityPersister(EntityManagerInterface $em, EntityPersister $persister, ClassMetadata $metadata);
/**
* Build a collection persister for the given relation mapping.
*
* @param \Doctrine\ORM\EntityManagerInterface $em The entity manager
* @param \Doctrine\ORM\Persisters\CollectionPersister $persister The collection persister
* @param array $mapping The association mapping
*
* @return \Doctrine\ORM\Cache\Persister\CachedCollectionPersister
*/
public function buildCachedCollectionPersister(EntityManagerInterface $em, CollectionPersister $persister, $mapping);
/**
* Build a query cache based on the given region name
*
* @param \Doctrine\ORM\EntityManagerInterface $em The Entity manager
* @param string $regionName The region name
*
* @return \Doctrine\ORM\Cache\QueryCache The built query cache.
*/
public function buildQueryCache(EntityManagerInterface $em, $regionName = null);
/**
* Build an entity hydrator
*
* @param \Doctrine\ORM\EntityManagerInterface $em The Entity manager.
* @param \Doctrine\ORM\Mapping\ClassMetadata $metadata The entity metadata.
*
* @return \Doctrine\ORM\Cache\EntityHydrator The built entity hydrator.
*/
public function buildEntityHydrator(EntityManagerInterface $em, ClassMetadata $metadata);
/**
* Build a collection hydrator
*
* @param \Doctrine\ORM\EntityManagerInterface $em The Entity manager.
* @param array $mapping The association mapping.
*
* @return \Doctrine\ORM\Cache\CollectionHydrator The built collection hydrator.
*/
public function buildCollectionHydrator(EntityManagerInterface $em, array $mapping);
/**
* Gets a cache region based on its name.
*
* @param array $cache The cache configuration.
*
* @return \Doctrine\ORM\Cache\Region The cache region.
*/
public function getRegion(array $cache);
/**
* Build timestamp cache region
*
* @return \Doctrine\ORM\Cache\TimestampRegion The timestamp region.
*/
public function getTimestampRegion();
}
`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.DefaultCacheFactory.html/>`_.
Region Lifetime
~~~~~~~~~~~~~~~
@ -428,81 +267,7 @@ By providing a cache logger you should be able to get information about all cach
If you want to get more information you should implement ``\Doctrine\ORM\Cache\Logging\CacheLogger``.
and collect all information you want.
.. code-block:: php
<?php
/**
* Log an entity put into second level cache.
*
* @param string $regionName The name of the cache region.
* @param EntityCacheKey $key The cache key of the entity.
*/
public function entityCachePut($regionName, EntityCacheKey $key);
/**
* Log an entity get from second level cache resulted in a hit.
*
* @param string $regionName The name of the cache region.
* @param EntityCacheKey $key The cache key of the entity.
*/
public function entityCacheHit($regionName, EntityCacheKey $key);
/**
* Log an entity get from second level cache resulted in a miss.
*
* @param string $regionName The name of the cache region.
* @param \EntityCacheKey $key The cache key of the entity.
*/
public function entityCacheMiss($regionName, EntityCacheKey $key);
/**
* Log an entity put into second level cache.
*
* @param string $regionName The name of the cache region.
* @param CollectionCacheKey $key The cache key of the collection.
*/
public function collectionCachePut($regionName, CollectionCacheKey $key);
/**
* Log an entity get from second level cache resulted in a hit.
*
* @param string $regionName The name of the cache region.
* @param CollectionCacheKey $key The cache key of the collection.
*/
public function collectionCacheHit($regionName, CollectionCacheKey $key);
/**
* Log an entity get from second level cache resulted in a miss.
*
* @param string $regionName The name of the cache region.
* @param \CollectionCacheKey $key The cache key of the collection.
*/
public function collectionCacheMiss($regionName, CollectionCacheKey $key);
/**
* Log a query put into the query cache.
*
* @param string $regionName The name of the cache region.
* @param QueryCacheKey $key The cache key of the query.
*/
public function queryCachePut($regionName, QueryCacheKey $key);
/**
* Log a query get from the query cache resulted in a hit.
*
* @param string $regionName The name of the cache region.
* @param \QueryCacheKey $key The cache key of the query.
*/
public function queryCacheHit($regionName, QueryCacheKey $key);
/**
* Log a query get from the query cache resulted in a miss.
*
* @param string $regionName The name of the cache region.
* @param QueryCacheKey $key The cache key of the query.
*/
public function queryCacheMiss($regionName, QueryCacheKey $key);
`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.CacheLogger.html/>`_.
Entity cache definition
@ -810,6 +575,47 @@ The Cache Mode controls how a particular query interacts with the second-level c
The the default query cache mode is ```Cache::MODE_NORMAL```
DELETE / UPDATE queries
~~~~~~~~~~~~~~~~~~~~~~~
DQL UPDATE / DELETE statements are ported directly into a database and bypass the second-level cache,
Entities that are already cached will NOT be invalidated.
However the cached data could be evicted using the cache API or an special query hint.
Execute the ``UPDATE`` and invalidate ``all cache entries`` using ``Query::HINT_CACHE_EVICT``
.. code-block:: php
<?php
// Execute and invalidate
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
->setHint(Query::HINT_CACHE_EVICT, true)
->execute();
Execute the ``UPDATE`` and invalidate ``all cache entries`` using the cache API
.. code-block:: php
<?php
// Execute
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
->execute();
// Invoke Cache API
$em->getCache()->evictEntityRegion('Entity\Country');
Execute the ``UPDATE`` and invalidate ``a specific cache entry`` using the cache API
.. code-block:: php
<?php
// Execute
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
->execute();
// Invoke Cache API
$em->getCache()->evictEntity('Entity\Country', 1);
Using the repository query cache
---------------------
@ -908,45 +714,12 @@ For performance reasons the cache API does not extract from composite primary ke
$id = array('source' => new Article(1), 'target' => new Article(2));
$reference = $em->find('Reference', $id);
DELETE / UPDATE queries
Distribute environments
~~~~~~~~~~~~~~~~~~~~~~~
DQL UPDATE / DELETE statements are ported directly into a database and bypass the second-level cache,
Entities that are already cached will NOT be invalidated.
However the cached data could be evicted using the cache API or an special query hint.
Some cache driver are not meant to be used in a distribute environment
Load-balancer for distributing workloads across multiple computing resources
should be used in conjunction with distributed caching system such as memcached, redis, riak ...
Execute the ``UPDATE`` and invalidate ``all cache entries`` using ``Query::HINT_CACHE_EVICT``
.. code-block:: php
<?php
// Execute and invalidate
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
->setHint(Query::HINT_CACHE_EVICT, true)
->execute();
Execute the ``UPDATE`` and invalidate ``all cache entries`` using the cache API
.. code-block:: php
<?php
// Execute
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
->execute();
// Invoke Cache API
$em->getCache()->evictEntityRegion('Entity\Country');
Execute the ``UPDATE`` and invalidate ``a specific cache entry`` using the cache API
.. code-block:: php
<?php
// Execute
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
->execute();
// Invoke Cache API
$em->getCache()->evictEntity('Entity\Country', 1);
Caches should be used with care when using a load-balancer if you don't share the cache.
While using APC or any file based cache update occurred in a specific machine would not reflect to the cache in other machines.

10
lib/Doctrine/ORM/AbstractQuery.php
View File

@ -346,9 +346,7 @@ abstract class AbstractQuery
$parameterCollection = new ArrayCollection();
foreach ($parameters as $key => $value) {
$parameter = new Parameter($key, $value);
$parameterCollection->add($parameter);
$parameterCollection->add(new Parameter($key, $value));
}
$parameters = $parameterCollection;
@ -387,9 +385,7 @@ abstract class AbstractQuery
return $this;
}
$parameter = new Parameter($key, $value, $type);
$this->parameters->add($parameter);
$this->parameters->add(new Parameter($key, $value, $type));
return $this;
}
@ -453,7 +449,7 @@ abstract class AbstractQuery
*
* @return \Doctrine\ORM\Query\ResultSetMapping
*/
public function getResultSetMapping()
protected function getResultSetMapping()
{
return $this->_resultSetMapping;
}

4
lib/Doctrine/ORM/Cache/CacheKey.php
View File

@ -21,7 +21,7 @@
namespace Doctrine\ORM\Cache;
/**
* Defines entity / collection key to be stored in the cache region.
* Defines entity / collection / query key to be stored in the cache region.
* Allows multiple roles to be stored in the same cache region.
*
* @since 2.5
@ -30,6 +30,8 @@ namespace Doctrine\ORM\Cache;
abstract class CacheKey
{
/**
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var string Unique identifier
*/
public $hash;

12
lib/Doctrine/ORM/Cache/CollectionCacheEntry.php
View File

@ -29,12 +29,14 @@ namespace Doctrine\ORM\Cache;
class CollectionCacheEntry implements CacheEntry
{
/**
* @var array
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var array The list of entity identifiers hold by the collection
*/
public $identifiers;
/**
* @param array $identifiers
* @param array $identifiers List of entity identifiers hold by the collection
*/
public function __construct(array $identifiers)
{
@ -42,7 +44,11 @@ class CollectionCacheEntry implements CacheEntry
}
/**
* @param array $values
* Creates a new CollectionCacheEntry
*
* This method allow Doctrine\Common\Cache\PhpFileCache compatibility
*
* @param array $values array containing property values
*/
public static function __set_state(array $values)
{

16
lib/Doctrine/ORM/Cache/CollectionCacheKey.php
View File

@ -29,17 +29,23 @@ namespace Doctrine\ORM\Cache;
class CollectionCacheKey extends CacheKey
{
/**
* @var array
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var array The owner entity identifier
*/
public $ownerIdentifier;
/**
* @var string
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var string The owner entity class
*/
public $entityClass;
/**
* @var string
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var string The association name
*/
public $association;
@ -52,9 +58,9 @@ class CollectionCacheKey extends CacheKey
{
ksort($ownerIdentifier);
$this->entityClass = $entityClass;
$this->association = $association;
$this->ownerIdentifier = $ownerIdentifier;
$this->entityClass = (string) $entityClass;
$this->association = (string) $association;
$this->hash = str_replace('\\', '.', strtolower($entityClass)) . '_' . implode(' ', $ownerIdentifier) . '__' . $association;
}
}

15
lib/Doctrine/ORM/Cache/DefaultCacheFactory.php
View File

@ -164,10 +164,15 @@ class DefaultCacheFactory implements CacheFactory
*/
public function buildQueryCache(EntityManagerInterface $em, $regionName = null)
{
return new DefaultQueryCache($em, $this->getRegion(array(
'region' => $regionName ?: Cache::DEFAULT_QUERY_REGION_NAME,
'usage' => ClassMetadata::CACHE_USAGE_NONSTRICT_READ_WRITE
)));
return new DefaultQueryCache(
$em,
$this->getRegion(
array(
'region' => $regionName ?: Cache::DEFAULT_QUERY_REGION_NAME,
'usage' => ClassMetadata::CACHE_USAGE_NONSTRICT_READ_WRITE
)
)
);
}
/**
@ -201,7 +206,7 @@ class DefaultCacheFactory implements CacheFactory
if ( ! $this->fileLockRegionDirectory) {
throw new \LogicException(
'If you want to use a "READ_WRITE" cache an implementation of "Doctrine\ORM\Cache\ConcurrentRegion" is required, ' .
'If you what to use a "READ_WRITE" cache an implementation of "Doctrine\ORM\Cache\ConcurrentRegion" is required, ' .
'The default implementation provided by doctrine is "Doctrine\ORM\Cache\Region\FileLockRegion" if you what to use it please provide a valid directory, DefaultCacheFactory#setFileLockRegionDirectory(). '
);
}

1
lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php
View File

@ -123,7 +123,6 @@ class DefaultEntityHydrator implements EntityHydrator
}
foreach ($metadata->associationMappings as $name => $assoc) {
if ( ! isset($assoc['cache']) || ! isset($data[$name])) {
continue;
}

14
lib/Doctrine/ORM/Cache/EntityCacheEntry.php
View File

@ -29,12 +29,16 @@ namespace Doctrine\ORM\Cache;
class EntityCacheEntry implements CacheEntry
{
/**
* @var array
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var array The entity map data
*/
public $data;
/**
* @var string
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var string The entity class name
*/
public $class;
@ -49,7 +53,11 @@ class EntityCacheEntry implements CacheEntry
}
/**
* @param array $values
* Creates a new EntityCacheEntry
*
* This method allow Doctrine\Common\Cache\PhpFileCache compatibility
*
* @param array $values array containing property values
*/
public static function __set_state(array $values)
{

8
lib/Doctrine/ORM/Cache/EntityCacheKey.php
View File

@ -29,12 +29,16 @@ namespace Doctrine\ORM\Cache;
class EntityCacheKey extends CacheKey
{
/**
* @var array
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var array The entity identifier
*/
public $identifier;
/**
* @var string
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var string The entity class name
*/
public $entityClass;

8
lib/Doctrine/ORM/Cache/QueryCacheEntry.php
View File

@ -29,12 +29,16 @@ namespace Doctrine\ORM\Cache;
class QueryCacheEntry implements CacheEntry
{
/**
* @var array
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var array List of entity identifiers
*/
public $result;
/**
* @var integer
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var integer Time creation of this cache entry
*/
public $time;

10
lib/Doctrine/ORM/Cache/QueryCacheKey.php
View File

@ -23,7 +23,7 @@ namespace Doctrine\ORM\Cache;
use Doctrine\ORM\Cache;
/**
* A key that identifies a particular query.
* A cache key that identifies a particular query.
*
* @since 2.5
* @author Fabio B. Silva <fabio.bat.silva@gmail.com>
@ -31,12 +31,16 @@ use Doctrine\ORM\Cache;
class QueryCacheKey extends CacheKey
{
/**
* @var integer
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var integer Cache key lifetime
*/
public $lifetime;
/**
* @var integer
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var integer Cache mode (Doctrine\ORM\Cache::MODE_*)
*/
public $cacheMode;

4
lib/Doctrine/ORM/Cache/Region/DefaultRegion.php
View File

@ -56,9 +56,9 @@ class DefaultRegion implements Region
*/
public function __construct($name, CacheProvider $cache, $lifetime = 0)
{
$this->name = $name;
$this->cache = $cache;
$this->lifetime = $lifetime;
$this->name = (string) $name;
$this->lifetime = (integer) $lifetime;
$this->cache->setNamespace($this->name);
}

10
lib/Doctrine/ORM/Cache/TimestampCacheEntry.php
View File

@ -29,6 +29,8 @@ namespace Doctrine\ORM\Cache;
class TimestampCacheEntry implements CacheEntry
{
/**
* READ-ONLY: Public only for performance reasons, it should be considered immutable.
*
* @var float
*/
public $time;
@ -38,11 +40,15 @@ class TimestampCacheEntry implements CacheEntry
*/
public function __construct($time = null)
{
$this->time = $time ?: microtime(true);
$this->time = $time ? (float)$time : microtime(true);
}
/**
* @param array $values
* Creates a new TimestampCacheEntry
*
* This method allow Doctrine\Common\Cache\PhpFileCache compatibility
*
* @param array $values array containing property values
*/
public static function __set_state(array $values)
{

2
lib/Doctrine/ORM/Cache/TimestampCacheKey.php
View File

@ -33,6 +33,6 @@ class TimestampCacheKey extends CacheKey
*/
public function __construct($space)
{
$this->hash = $space;
$this->hash = (string) $space;
}
}

9
lib/Doctrine/ORM/Mapping/Driver/AnnotationDriver.php
View File

@ -131,11 +131,12 @@ class AnnotationDriver extends AbstractAnnotationDriver
// Evaluate @Cache annotation
if (isset($classAnnotations['Doctrine\ORM\Mapping\Cache'])) {
$cacheAnnot = $classAnnotations['Doctrine\ORM\Mapping\Cache'];
$cacheMap = array(
'region' => $cacheAnnot->region,
'usage' => constant('Doctrine\ORM\Mapping\ClassMetadata::CACHE_USAGE_' . $cacheAnnot->usage),
);
$metadata->enableCache(array(
'usage' => constant('Doctrine\ORM\Mapping\ClassMetadata::CACHE_USAGE_' . $cacheAnnot->usage),
'region' => $cacheAnnot->region,
));
$metadata->enableCache($cacheMap);
}
// Evaluate NamedNativeQueries annotation

2
lib/Doctrine/ORM/Query.php
View File

@ -215,7 +215,7 @@ final class Query extends AbstractQuery
/**
* {@inheritdoc}
*/
public function getResultSetMapping()
protected function getResultSetMapping()
{
// parse query or load from cache
if ($this->_resultSetMapping === null) {

2
tests/Doctrine/Tests/ORM/Cache/DefaultCacheFactoryTest.php
View File

@ -253,7 +253,7 @@ class DefaultCacheFactoryTest extends OrmTestCase
/**
* @expectedException LogicException
* @expectedExceptionMessage If you want to use a "READ_WRITE" cache an implementation of "Doctrine\ORM\Cache\ConcurrentRegion" is required, The default implementation provided by doctrine is "Doctrine\ORM\Cache\Region\FileLockRegion" if you what to use it please provide a valid directory
* @expectedExceptionMessage If you what to use a "READ_WRITE" cache an implementation of "Doctrine\ORM\Cache\ConcurrentRegion" is required, The default implementation provided by doctrine is "Doctrine\ORM\Cache\Region\FileLockRegion" if you what to use it please provide a valid directory
*/
public function testInvalidFileLockRegionDirectoryException()
{