1Configuration 2============= 3 4.. note :: 5 6 If you are using Symfony2, this section is mostly irrelevant for you as the entire integration is provided by 7 JMSSerializerBundle; please see `its documentation <http://jmsyst.com/bundles/JMSSerializerBundle>`_. If you are 8 using another framework, there also might be a module, or other special integration. Please check packagist, or 9 whatever registry usually holds such information for your framework. 10 11 12If you are using the standalone library and you want to use annotations, the annotation registry must be initialized:: 13 14 Doctrine\Common\Annotations\AnnotationRegistry::registerLoader('class_exists'); 15 16 17Constructing a Serializer 18------------------------- 19 20This library provides a special builder object which makes constructing serializer instances a breeze in any PHP 21project. In its shortest version, it's just a single line of code:: 22 23 $serializer = JMS\Serializer\SerializerBuilder::create()->build(); 24 25This serializer is fully functional, but you might want to tweak it a bit for example to configure a cache directory. 26 27Configuring a Cache Directory 28----------------------------- 29The serializer collects several metadata about your objects from various sources such as YML, XML, or annotations. In 30order to make this process as efficient as possible, it is encourage to let the serializer cache that information. For 31that, you can configure a cache directory:: 32 33 $builder = new JMS\Serializer\SerializerBuilder(); 34 35 $serializer = 36 JMS\Serializer\SerializerBuilder::create() 37 ->setCacheDir($someWritableDir) 38 ->setDebug($trueOrFalse) 39 ->build(); 40 41As you can see, we also added a call to the ``setDebug`` method. In debug mode, the serializer will perform a bit more 42filesystem checks to see whether the data that it has cached is still valid. These checks are useful during development 43so that you do not need to manually clear cache folders, however in production they are just unnecessary overhead. The 44debug setting allows you to make the behavior environment specific. 45 46Adding Custom Handlers 47---------------------- 48If you have created custom handlers, you can add them to the serializer easily:: 49 50 $serializer = 51 JMS\Serializer\SerializerBuilder::create() 52 ->addDefaultHandlers() 53 ->configureHandlers(function(JMS\Serializer\Handler\HandlerRegistry $registry) { 54 $registry->registerHandler('serialization', 'MyObject', 'json', 55 function($visitor, MyObject $obj, array $type) { 56 return $obj->getName(); 57 } 58 ); 59 }) 60 ->build(); 61 62For more complex handlers, it is advisable to extract them to dedicated classes, 63see :doc:`handlers documentation <handlers>`. 64 65Configuring Metadata Locations 66------------------------------ 67This library supports several metadata sources. By default, it uses Doctrine annotations, but you may also store 68metadata in XML, or YML files. For the latter, it is necessary to configure a metadata directory where those files 69are located:: 70 71 $serializer = 72 JMS\Serializer\SerializerBuilder::create() 73 ->addMetadataDir($someDir) 74 ->build(); 75 76The serializer would expect the metadata files to be named like the fully qualified class names where all ``\`` are 77replaced with ``.``. So, if you class would be named ``Vendor\Package\Foo``, the metadata file would need to be located 78at ``$someDir/Vendor.Package.Foo.(xml|yml)``. For more information, see the :doc:`reference <reference>`. 79 80Setting a default SerializationContext factory 81---------------------------------------------- 82To avoid to pass an instance of SerializationContext 83every time you call method ``serialize()`` (or ``toArray()``), 84you can set a ``SerializationContextFactory`` to the Serializer. 85 86Example using the SerializerBuilder:: 87 88 use JMS\Serializer\SerializationContext; 89 90 $serializer = JMS\Serializer\SerializerBuilder::create() 91 ->setSerializationContextFactory(function () { 92 return SerializationContext::create() 93 ->setSerializeNull(true) 94 ; 95 }) 96 ->build() 97 ; 98 99Then, calling ``$serializer->serialize($data, 'json');`` will generate 100a serialization context from your callable and use it. 101 102.. note :: 103 104 You can also set a default DeserializationContextFactory with 105 ``->setDeserializationContextFactory(function () { /* ... */ })`` 106 to be used with methods ``deserialize()`` and ``fromArray()``. 107