Skip to content

Commit 0a12b68

Browse files
humandbweaverryan
humandb
authored and
weaverryan
committed
Adding first draft for the serializer component
1 parent ba1d04a commit 0a12b68

File tree

1 file changed

+280
-0
lines changed

1 file changed

+280
-0
lines changed

‎components/serializer.rst

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
.. index::
2+
single: Serializer
3+
single: Components; Serializer
4+
5+
The Serializer Component
6+
====================
7+
8+
The Serializer Component is meant to be used to turn Objects into a
9+
specific format (XML, JSON, Yaml, ...) and the other way around.
10+
11+
In order to do so, the Serializer Components follows the following
12+
simple schema.
13+
14+
As you can see in the picture above, an array is used as a man in
15+
the middle. This way, Encoders will only deal with turning specific
16+
formats into arrays and vice versa, and Normalizer will deal with
17+
turning specific objects into arrays and vice versa.
18+
19+
From the graph above is also clear what encoding, decoding, normalize,
20+
denormalize, serialize and deserialize mean.
21+
22+
Installation
23+
------------
24+
25+
You can install the component in many different ways:
26+
27+
* Use the official Git repository (https://github.com/symfony/Serializer);
28+
* Install it via PEAR ( `pear.symfony.com/Serializer`);
29+
* Install it via Composer (`symfony/serializer` on Packagist).
30+
31+
Encoders
32+
--------
33+
34+
The :class:`Symfony\\Component\\Finder\\Finder` class finds files and/or
35+
directories::
36+
37+
use Symfony\Component\Finder\Finder;
38+
39+
$finder = new Finder();
40+
$finder->files()->in(__DIR__);
41+
42+
foreach ($finder as $file) {
43+
// Print the absolute path
44+
print $file->getRealpath()."\n";
45+
46+
// Print the relative path to the file, omitting the filename
47+
print $file->getRelativePath()."\n";
48+
49+
// Print the relative path to the file
50+
print $file->getRelativePathname()."\n";
51+
}
52+
53+
The ``$file`` is an instance of :class:`Symfony\\Component\\Finder\\SplFileInfo`
54+
which extends :phpclass:`SplFileInfo` to provide methods to work with relative
55+
paths.
56+
57+
The above code prints the names of all the files in the current directory
58+
recursively. The Finder class uses a fluent interface, so all methods return
59+
the Finder instance.
60+
61+
.. tip::
62+
63+
A Finder instance is a PHP `Iterator`_. So, instead of iterating over the
64+
Finder with ``foreach``, you can also convert it to an array with the
65+
:phpfunction:`iterator_to_array` method, or get the number of items with
66+
:phpfunction:`iterator_count`.
67+
68+
Criteria
69+
--------
70+
71+
Location
72+
~~~~~~~~
73+
74+
The location is the only mandatory criteria. It tells the finder which
75+
directory to use for the search::
76+
77+
$finder->in(__DIR__);
78+
79+
Search in several locations by chaining calls to
80+
:method:`Symfony\\Component\\Finder\\Finder::in`::
81+
82+
$finder->files()->in(__DIR__)->in('/elsewhere');
83+
84+
Exclude directories from matching with the
85+
:method:`Symfony\\Component\\Finder\\Finder::exclude` method::
86+
87+
$finder->in(__DIR__)->exclude('ruby');
88+
89+
As the Finder uses PHP iterators, you can pass any URL with a supported
90+
`protocol`_::
91+
92+
$finder->in('ftp://example.com/pub/');
93+
94+
And it also works with user-defined streams::
95+
96+
use Symfony\Component\Finder\Finder;
97+
98+
$s3 = new \Zend_Service_Amazon_S3($key, $secret);
99+
$s3->registerStreamWrapper("s3");
100+
101+
$finder = new Finder();
102+
$finder->name('photos*')->size('< 100K')->date('since 1 hour ago');
103+
foreach ($finder->in('s3://bucket-name') as $file) {
104+
// ... do something
105+
106+
print $file->getFilename()."\n";
107+
}
108+
109+
.. note::
110+
111+
Read the `Streams`_ documentation to learn how to create your own streams.
112+
113+
Files or Directories
114+
~~~~~~~~~~~~~~~~~~~~~
115+
116+
By default, the Finder returns files and directories; but the
117+
:method:`Symfony\\Component\\Finder\\Finder::files` and
118+
:method:`Symfony\\Component\\Finder\\Finder::directories` methods control that::
119+
120+
$finder->files();
121+
122+
$finder->directories();
123+
124+
If you want to follow links, use the ``followLinks()`` method::
125+
126+
$finder->files()->followLinks();
127+
128+
By default, the iterator ignores popular VCS files. This can be changed with
129+
the ``ignoreVCS()`` method::
130+
131+
$finder->ignoreVCS(false);
132+
133+
Sorting
134+
~~~~~~~
135+
136+
Sort the result by name or by type (directories first, then files)::
137+
138+
$finder->sortByName();
139+
140+
$finder->sortByType();
141+
142+
.. note::
143+
144+
Notice that the ``sort*`` methods need to get all matching elements to do
145+
their jobs. For large iterators, it is slow.
146+
147+
You can also define your own sorting algorithm with ``sort()`` method::
148+
149+
$sort = function (\SplFileInfo $a, \SplFileInfo $b)
150+
{
151+
return strcmp($a->getRealpath(), $b->getRealpath());
152+
};
153+
154+
$finder->sort($sort);
155+
156+
File Name
157+
~~~~~~~~~
158+
159+
Restrict files by name with the
160+
:method:`Symfony\\Component\\Finder\\Finder::name` method::
161+
162+
$finder->files()->name('*.php');
163+
164+
The ``name()`` method accepts globs, strings, or regexes::
165+
166+
$finder->files()->name('/\.php$/');
167+
168+
The ``notName()`` method excludes files matching a pattern::
169+
170+
$finder->files()->notName('*.rb');
171+
172+
File Contents
173+
~~~~~~~~~~~~~
174+
175+
.. versionadded:: 2.1
176+
Methods ``contains()`` and ``notContains()`` have been
177+
introduced in version 2.1.
178+
179+
Restrict files by contents with the
180+
:method:`Symfony\\Component\\Finder\\Finder::contains` method::
181+
182+
$finder->files()->contains('lorem ipsum');
183+
184+
The ``contains()`` method accepts strings or regexes::
185+
186+
$finder->files()->contains('/lorem\s+ipsum$/i');
187+
188+
The ``notContains()`` method excludes files containing given pattern::
189+
190+
$finder->files()->notContains('dolor sit amet');
191+
192+
File Size
193+
~~~~~~~~~
194+
195+
Restrict files by size with the
196+
:method:`Symfony\\Component\\Finder\\Finder::size` method::
197+
198+
$finder->files()->size('< 1.5K');
199+
200+
Restrict by a size range by chaining calls::
201+
202+
$finder->files()->size('>= 1K')->size('<= 2K');
203+
204+
The comparison operator can be any of the following: ``>``, ``>=``, ``<``, ``<=``,
205+
``==``, ``!=``.
206+
207+
.. versionadded:: 2.1
208+
The operator ``!=`` was added in version 2.1.
209+
210+
The target value may use magnitudes of kilobytes (``k``, ``ki``), megabytes
211+
(``m``, ``mi``), or gigabytes (``g``, ``gi``). Those suffixed with an ``i`` use
212+
the appropriate ``2**n`` version in accordance with the `IEC standard`_.
213+
214+
File Date
215+
~~~~~~~~~
216+
217+
Restrict files by last modified dates with the
218+
:method:`Symfony\\Component\\Finder\\Finder::date` method::
219+
220+
$finder->date('since yesterday');
221+
222+
The comparison operator can be any of the following: ``>``, ``>=``, ``<``, '<=',
223+
'=='. You can also use ``since`` or ``after`` as an alias for ``>``, and
224+
``until`` or ``before`` as an alias for ``<``.
225+
226+
The target value can be any date supported by the `strtotime`_ function.
227+
228+
Directory Depth
229+
~~~~~~~~~~~~~~~
230+
231+
By default, the Finder recursively traverse directories. Restrict the depth of
232+
traversing with :method:`Symfony\\Component\\Finder\\Finder::depth`::
233+
234+
$finder->depth('== 0');
235+
$finder->depth('< 3');
236+
237+
Custom Filtering
238+
~~~~~~~~~~~~~~~~
239+
240+
To restrict the matching file with your own strategy, use
241+
:method:`Symfony\\Component\\Finder\\Finder::filter`::
242+
243+
$filter = function (\SplFileInfo $file)
244+
{
245+
if (strlen($file) > 10) {
246+
return false;
247+
}
248+
};
249+
250+
$finder->files()->filter($filter);
251+
252+
The ``filter()`` method takes a Closure as an argument. For each matching file,
253+
it is called with the file as a :class:`Symfony\\Component\\Finder\\SplFileInfo`
254+
instance. The file is excluded from the result set if the Closure returns
255+
``false``.
256+
257+
Reading contents of returned files
258+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259+
260+
.. versionadded:: 2.1
261+
Method ``getContents()`` have been introduced in version 2.1.
262+
263+
The contents of returned files can be read with
264+
:method:`Symfony\\Component\\Finder\\SplFileInfo::getContents`::
265+
266+
use Symfony\Component\Finder\Finder;
267+
268+
$finder = new Finder();
269+
$finder->files()->in(__DIR__);
270+
271+
foreach ($finder as $file) {
272+
$contents = $file->getContents();
273+
...
274+
}
275+
276+
.. _strtotime: http://www.php.net/manual/en/datetime.formats.php
277+
.. _Iterator: http://www.php.net/manual/en/spl.iterators.php
278+
.. _protocol: http://www.php.net/manual/en/wrappers.php
279+
.. _Streams: http://www.php.net/streams
280+
.. _IEC standard: http://physics.nist.gov/cuu/Units/binary.html

0 commit comments

Comments
 (0)