Hello World!
'); - -print $crawler->filter('body > p')->text(); -``` - -By the way, that's one example of a component (DomCrawler) that relies -on another one (CssSelector) for some optional features. + print CssSelector::toXPath('div.item > h4 > a'); Resources --------- @@ -36,3 +16,8 @@ Resources Unit tests: https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/CssSelector + +This component is a port of the Python lxml library, which is copyright Infrae +and distributed under the BSD license. + +Current code is a port of http://codespeak.net/svn/lxml/trunk/src/lxml/cssselect.py@71545 diff --git a/src/Symfony/Component/DependencyInjection/README.md b/src/Symfony/Component/DependencyInjection/README.md index 3c6847dcb733..6add4cb92b58 100644 --- a/src/Symfony/Component/DependencyInjection/README.md +++ b/src/Symfony/Component/DependencyInjection/README.md @@ -1,22 +1,22 @@ DependencyInjection Component ============================= -Even the DependencyInjection component is really easy. It has many features, but its core -is simple to use. See how easy it is to configure a service that relies on another service: - -``` -use Symfony\Component\DependencyInjection\ContainerBuilder; -use Symfony\Component\DependencyInjection\Reference; - -$sc = new ContainerBuilder(); -$sc - ->register('foo', '%foo.class%') - ->addArgument(new Reference('bar')) -; -$sc->setParameter('foo.class', 'Foo'); - -$sc->get('foo'); -``` +DependencyInjection manages your services via a robust and flexible Dependency +Injection Container. + +Here is a simple example that shows how to register services and parameters: + + use Symfony\Component\DependencyInjection\ContainerBuilder; + use Symfony\Component\DependencyInjection\Reference; + + $sc = new ContainerBuilder(); + $sc + ->register('foo', '%foo.class%') + ->addArgument(new Reference('bar')) + ; + $sc->setParameter('foo.class', 'Foo'); + + $sc->get('foo'); Resources --------- diff --git a/src/Symfony/Component/DomCrawler/README.md b/src/Symfony/Component/DomCrawler/README.md index fd1255193502..9a2d2611f0a9 100644 --- a/src/Symfony/Component/DomCrawler/README.md +++ b/src/Symfony/Component/DomCrawler/README.md @@ -1,17 +1,26 @@ DomCrawler Component ==================== -If you are familiar with jQuery, DomCrawler is a PHP equivalent. -It allows you to navigate the DOM of an HTML or XML document: +DomCrawler eases DOM navigation for HTML and XML documents. -``` -use Symfony\Component\DomCrawler\Crawler; +If you are familiar with jQuery, DomCrawler is a PHP equivalent: -$crawler = new Crawler(); -$crawler->addContent('Hello World!
'); + use Symfony\Component\DomCrawler\Crawler; -print $crawler->filterXPath('descendant-or-self::body/p')->text(); -``` + $crawler = new Crawler(); + $crawler->addContent('Hello World!
'); + + print $crawler->filterXPath('descendant-or-self::body/p')->text(); + +If you are also using the CssSelector component, you can use CSS Selectors +instead of XPath expressions: + + use Symfony\Component\DomCrawler\Crawler; + + $crawler = new Crawler(); + $crawler->addContent('Hello World!
'); + + print $crawler->filter('body > p')->text(); Resources --------- diff --git a/src/Symfony/Component/EventDispatcher/README.md b/src/Symfony/Component/EventDispatcher/README.md index d68784ddb4e6..9427d75645eb 100644 --- a/src/Symfony/Component/EventDispatcher/README.md +++ b/src/Symfony/Component/EventDispatcher/README.md @@ -1,18 +1,19 @@ EventDispatcher Component ========================= -``` -use Symfony\Component\EventDispatcher\EventDispatcher; -use Symfony\Component\EventDispatcher\Event; +EventDispatcher implements a lightweight version of the Observer design +pattern. -$dispatcher = new EventDispatcher(); + use Symfony\Component\EventDispatcher\EventDispatcher; + use Symfony\Component\EventDispatcher\Event; -$dispatcher->addListener('event_name', function (Event $event) { - // ... -}); + $dispatcher = new EventDispatcher(); -$dispatcher->dispatch('event_name'); -``` + $dispatcher->addListener('event_name', function (Event $event) { + // ... + }); + + $dispatcher->dispatch('event_name'); Resources --------- diff --git a/src/Symfony/Component/Finder/README.md b/src/Symfony/Component/Finder/README.md index 787dd1eaf8a4..3e71447f3abd 100644 --- a/src/Symfony/Component/Finder/README.md +++ b/src/Symfony/Component/Finder/README.md @@ -1,39 +1,34 @@ Finder Component ================ -The Finder provides a very convenient and nice fluent interface to find files -and directories on the filesystem: +Finder finds files and directories via an intuitive fluent interface. -``` -use Symfony\Component\Finder\Finder; + use Symfony\Component\Finder\Finder; -$finder = new Finder(); + $finder = new Finder(); -$iterator = $finder - ->files() - ->name('*.php') - ->depth(0) - ->size('>= 1K') - ->in(__DIR__); + $iterator = $finder + ->files() + ->name('*.php') + ->depth(0) + ->size('>= 1K') + ->in(__DIR__); -foreach ($iterator as $file) { - print $file->getRealpath()."\n"; -} -``` + foreach ($iterator as $file) { + print $file->getRealpath()."\n"; + } But you can also use it to find files stored remotely like in this example where we are looking for files on Amazon S3: -``` -$s3 = new \Zend_Service_Amazon_S3($key, $secret); -$s3->registerStreamWrapper("s3"); + $s3 = new \Zend_Service_Amazon_S3($key, $secret); + $s3->registerStreamWrapper("s3"); -$finder = new Finder(); -$finder->name('photos*')->size('< 100K')->date('since 1 hour ago'); -foreach ($finder->in('s3://bucket-name') as $file) { - print $file->getFilename()."\n"; -} -``` + $finder = new Finder(); + $finder->name('photos*')->size('< 100K')->date('since 1 hour ago'); + foreach ($finder->in('s3://bucket-name') as $file) { + print $file->getFilename()."\n"; + } Resources --------- diff --git a/src/Symfony/Component/Form/README.md b/src/Symfony/Component/Form/README.md index 982d3868b4ca..15b0bdd4d47f 100644 --- a/src/Symfony/Component/Form/README.md +++ b/src/Symfony/Component/Form/README.md @@ -1,13 +1,17 @@ Form Component ============== -The Symfony2 Form component provides tools for defining forms, rendering and -binding request data to related models. Furthermore it provides integration -with the Validation component. +Form provides tools for defining forms, rendering and binding request data to +related models. Furthermore it provides integration with the Validation +component. Resources --------- +Silex integration: + +https://github.com/fabpot/Silex/blob/master/src/Silex/Provider/FormServiceProvider.php + Unit tests: https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Form diff --git a/src/Symfony/Component/HttpFoundation/README.md b/src/Symfony/Component/HttpFoundation/README.md index aa3a4e7d379a..67823e7f7012 100644 --- a/src/Symfony/Component/HttpFoundation/README.md +++ b/src/Symfony/Component/HttpFoundation/README.md @@ -1,34 +1,32 @@ HttpFoundation Component ======================== -The Symfony2 HttpFoundation component adds an object-oriented layer on top of PHP for -everything related to the Web: Requests, Responses, Uploaded files, Cookies, Sessions, ... +HttpFoundation defines an object-oriented layer for the HTTP specification. -In this example, we get a Request object from the current PHP global variables: +It provides an abstraction for requests, responses, uploaded files, cookies, +sessions, ... -``` -use Symfony\Component\HttpFoundation\Request; -use Symfony\Component\HttpFoundation\Response; +In this example, we get a Request object from the current PHP global +variables: -$request = Request::createFromGlobals(); -echo $request->getPathInfo(); -``` + use Symfony\Component\HttpFoundation\Request; + use Symfony\Component\HttpFoundation\Response; + + $request = Request::createFromGlobals(); + echo $request->getPathInfo(); You can also create a Request directly -- that's interesting for unit testing: -``` -$request = Request::create('/?foo=bar', 'GET'); -echo $request->getPathInfo(); -``` + $request = Request::create('/?foo=bar', 'GET'); + echo $request->getPathInfo(); And here is how to create and send a Response: -``` -$response = new Response('Not Found', 404, array('Content-Type' => 'text/plain')); -$response->send(); -``` + $response = new Response('Not Found', 404, array('Content-Type' => 'text/plain')); + $response->send(); -The Request and the Response classes have many other methods that implement the HTTP specification. +The Request and the Response classes have many other methods that implement +the HTTP specification. Resources --------- diff --git a/src/Symfony/Component/HttpKernel/README.md b/src/Symfony/Component/HttpKernel/README.md index f3b0f65ae1fe..64b19445ec5e 100644 --- a/src/Symfony/Component/HttpKernel/README.md +++ b/src/Symfony/Component/HttpKernel/README.md @@ -1,89 +1,83 @@ HttpKernel Component ==================== -The HttpKernel component provides the dynamic part of the HTTP specification. -It provides the HttpKernelInterface, which is the core interface of the Symfony2 -full-stack framework: - -``` -interface HttpKernelInterface -{ - /** - * Handles a Request to convert it to a Response. - * - * @param Request $request A Request instance - * - * @return Response A Response instance - */ - function handle(Request $request, $type = self::MASTER_REQUEST, $catch = true); -} -``` - -It takes a Request as an input and should return a Response as an output. Using this -interface makes your code compatible with all frameworks using the Symfony2 components. -And this will gives you many cool features for free. - -Creating a framework based on the Symfony2 components is really easy. Here is a very -simple, but fully-featured framework based on the Symfony2 components: - -``` -$routes = new RouteCollection(); -$routes->add('hello', new Route('/hello', array('_controller' => - function (Request $request) { - return new Response(sprintf("Hello %s", $request->get('name'))); +HttpKernel provides the building blocks to create flexible and fast HTTP-based +frameworks. + +``HttpKernelInterface`` is the core interface of the Symfony2 full-stack +framework: + + interface HttpKernelInterface + { + /** + * Handles a Request to convert it to a Response. + * + * @param Request $request A Request instance + * + * @return Response A Response instance + */ + function handle(Request $request, $type = self::MASTER_REQUEST, $catch = true); } -))); -$request = Request::createFromGlobals(); +It takes a ``Request`` as an input and should return a ``Response`` as an +output. Using this interface makes your code compatible with all frameworks +using the Symfony2 components. And this will gives you many cool features for +free. -$context = new RequestContext(); -$context->fromRequest($request); +Creating a framework based on the Symfony2 components is really easy. Here is +a very simple, but fully-featured framework based on the Symfony2 components: -$matcher = new UrlMatcher($routes, $context); + $routes = new RouteCollection(); + $routes->add('hello', new Route('/hello', array('_controller' => + function (Request $request) { + return new Response(sprintf("Hello %s", $request->get('name'))); + } + ))); -$dispatcher = new EventDispatcher(); -$dispatcher->addSubscriber(new RouterListener($matcher)); + $request = Request::createFromGlobals(); -$resolver = new ControllerResolver(); + $context = new RequestContext(); + $context->fromRequest($request); -$kernel = new HttpKernel($dispatcher, $resolver); + $matcher = new UrlMatcher($routes, $context); -$kernel->handle($request)->send(); -``` + $dispatcher = new EventDispatcher(); + $dispatcher->addSubscriber(new RouterListener($matcher)); -This is all you need to create a flexible framework with the Symfony2 components. + $resolver = new ControllerResolver(); -Want to add an HTTP reverse proxy and benefit from HTTP caching and Edge Side Includes? + $kernel = new HttpKernel($dispatcher, $resolver); -``` -$kernel = new HttpKernel($dispatcher, $resolver); + $kernel->handle($request)->send(); -$kernel = new HttpCache($kernel, new Store(__DIR__.'/cache')); -``` +This is all you need to create a flexible framework with the Symfony2 +components. + +Want to add an HTTP reverse proxy and benefit from HTTP caching and Edge Side +Includes? + + $kernel = new HttpKernel($dispatcher, $resolver); + + $kernel = new HttpCache($kernel, new Store(__DIR__.'/cache')); Want to functional test this small framework? -``` -$client = new Client($kernel); -$crawler = $client->request('GET', '/hello/Fabien'); + $client = new Client($kernel); + $crawler = $client->request('GET', '/hello/Fabien'); -$this->assertEquals('Fabien', $crawler->filter('p > span')->text()); -``` + $this->assertEquals('Fabien', $crawler->filter('p > span')->text()); Want nice error pages instead of ugly PHP exceptions? -``` -$dispatcher->addSubscriber(new ExceptionListener(function (Request $request) { - $msg = 'Something went wrong! ('.$request->get('exception')->getMessage().')'; - - return new Response($msg, 500); -})); -``` + $dispatcher->addSubscriber(new ExceptionListener(function (Request $request) { + $msg = 'Something went wrong! ('.$request->get('exception')->getMessage().')'; -I can continue on and on but I think you get the point. + return new Response($msg, 500); + })); -And that's why the simple looking HttpKernelInterface is so powerful. -It gives you access to a lot of cool features, ready to be used out of the box, with no efforts. +And that's why the simple looking ``HttpKernelInterface`` is so powerful. It +gives you access to a lot of cool features, ready to be used out of the box, +with no efforts. Resources --------- diff --git a/src/Symfony/Component/Locale/README.md b/src/Symfony/Component/Locale/README.md index 224a0cc37105..4fece8b38a1d 100644 --- a/src/Symfony/Component/Locale/README.md +++ b/src/Symfony/Component/Locale/README.md @@ -1,19 +1,18 @@ Locale Component ================ -Provides fallback code to handle cases when the intl extension is missing. +Locale provides fallback code to handle cases when the ``intl`` extension is +missing. Loading the fallback classes for example using the ClassLoader component only -requires adding the following lines to your autoloader. +requires adding the following lines to your autoloader: -``` -// intl -if (!function_exists('intl_get_error_code')) { - require __DIR__.'/../vendor/symfony/src/Symfony/Component/Locale/Resources/stubs/functions.php'; + // intl + if (!function_exists('intl_get_error_code')) { + require __DIR__.'/../vendor/symfony/src/Symfony/Component/Locale/Resources/stubs/functions.php'; - $loader->registerPrefixFallbacks(array(__DIR__.'/../vendor/symfony/src/Symfony/Component/Locale/Resources/stubs')); -} -``` + $loader->registerPrefixFallbacks(array(__DIR__.'/../vendor/symfony/src/Symfony/Component/Locale/Resources/stubs')); + } Resources --------- diff --git a/src/Symfony/Component/Process/README.md b/src/Symfony/Component/Process/README.md index 8d6536ffe002..8a197afff78e 100644 --- a/src/Symfony/Component/Process/README.md +++ b/src/Symfony/Component/Process/README.md @@ -1,40 +1,38 @@ Process Component ================= -The Process component allows you to execute a command in a sub-process. -In this example, I run a simple directory listing and get the result back: +Process executes commands in sub-processes. -``` -use Symfony\Component\Process\Process; +In this example, we run a simple directory listing and get the result back: -$process = new Process('ls -lsa'); -$process->setTimeout(3600); -$process->run(); -if (!$process->isSuccessful()) { - throw new RuntimeException($process->getErrorOutput()); -} + use Symfony\Component\Process\Process; -print $process->getOutput(); -``` + $process = new Process('ls -lsa'); + $process->setTimeout(3600); + $process->run(); + if (!$process->isSuccessful()) { + throw new RuntimeException($process->getErrorOutput()); + } + + print $process->getOutput(); You can think that this is easy to achieve with plain PHP but it's not especially if you want to take care of the subtle differences between the different platforms. -And if you want to be able to get some feedback in real-time, just pass an anonymous -function to the run() method and you will get the output buffer as it becomes available: +And if you want to be able to get some feedback in real-time, just pass an +anonymous function to the ``run()`` method and you will get the output buffer +as it becomes available: -``` -use Symfony\Component\Process\Process; + use Symfony\Component\Process\Process; -$process = new Process('ls -lsa'); -$process->run(function ($type, $buffer) { - if ('err' === $type) { - echo 'ERR > '.$buffer; - } else { - echo 'OUT > '.$buffer; - } -}); -``` + $process = new Process('ls -lsa'); + $process->run(function ($type, $buffer) { + if ('err' === $type) { + echo 'ERR > '.$buffer; + } else { + echo 'OUT > '.$buffer; + } + }); That's great if you want to execute a long running command (like rsync-ing files to a remote server) and give feedback to the user in real-time. diff --git a/src/Symfony/Component/Routing/README.md b/src/Symfony/Component/Routing/README.md index ec92b14742a7..eb72334d2ea9 100644 --- a/src/Symfony/Component/Routing/README.md +++ b/src/Symfony/Component/Routing/README.md @@ -1,29 +1,28 @@ Routing Component ================= -The Routing component is a way to associate a Request with the code that will -convert it somehow to a Response. The example below demonstrates that with only -10 lines of code, you can set up a fully working routing system: +Routing associates a request with the code that will convert it to a response. -``` -use Symfony\Component\HttpFoundation\Request; -use Symfony\Component\Routing\Matcher\UrlMatcher; -use Symfony\Component\Routing\RequestContext; -use Symfony\Component\Routing\RouteCollection; -use Symfony\Component\Routing\Route; +The example below demonstrates how you can set up a fully working routing +system: -$routes = new RouteCollection(); -$routes->add('hello', new Route('/hello', array('controller' => 'foo'))); + use Symfony\Component\HttpFoundation\Request; + use Symfony\Component\Routing\Matcher\UrlMatcher; + use Symfony\Component\Routing\RequestContext; + use Symfony\Component\Routing\RouteCollection; + use Symfony\Component\Routing\Route; -$context = new RequestContext(); + $routes = new RouteCollection(); + $routes->add('hello', new Route('/hello', array('controller' => 'foo'))); -// this is optional and can be done without a Request instance -$context->fromRequest(Request::createFromGlobals()); + $context = new RequestContext(); -$matcher = new UrlMatcher($routes, $context); + // this is optional and can be done without a Request instance + $context->fromRequest(Request::createFromGlobals()); -$parameters = $matcher->match('/hello'); -``` + $matcher = new UrlMatcher($routes, $context); + + $parameters = $matcher->match('/hello'); Resources --------- diff --git a/src/Symfony/Component/Security/README.md b/src/Symfony/Component/Security/README.md index e25f40e6463d..7aea89068b9d 100644 --- a/src/Symfony/Component/Security/README.md +++ b/src/Symfony/Component/Security/README.md @@ -1,10 +1,10 @@ Security Component ================== -This component provides an infrastructure for sophisticated authorization systems, -which makes it possible to easily separate the actual authorization logic from so -called user providers that hold the users credentials. It is inspired by the -Java Spring framework. +Security provides an infrastructure for sophisticated authorization systems, +which makes it possible to easily separate the actual authorization logic from +so called user providers that hold the users credentials. It is inspired by +the Java Spring framework. Resources --------- diff --git a/src/Symfony/Component/Templating/README.md b/src/Symfony/Component/Templating/README.md index 5b979cdd2fba..4a50b6561af9 100644 --- a/src/Symfony/Component/Templating/README.md +++ b/src/Symfony/Component/Templating/README.md @@ -1,10 +1,12 @@ Templating Component ==================== -This component provides an infrastructure to load template files and optionally -monitor them for changes. It also provides a concrete template engine implementation -using PHP with additional tools for escaping and separating templates into blocks -and layouts. +Templating provides all the tools needed to build any kind of template system. + +It provides an infrastructure to load template files and optionally monitor +them for changes. It also provides a concrete template engine implementation +using PHP with additional tools for escaping and separating templates into +blocks and layouts. Resources --------- diff --git a/src/Symfony/Component/Translation/README.md b/src/Symfony/Component/Translation/README.md index 257e15a33340..9afd9f82066c 100644 --- a/src/Symfony/Component/Translation/README.md +++ b/src/Symfony/Component/Translation/README.md @@ -1,12 +1,29 @@ Translation Component ===================== -This component provides tools for loading translation files and generating translated -strings from these including support for pluralization. +Translation provides tools for loading translation files and generating +translated strings from these including support for pluralization. + + use Symfony\Component\Translation\Translator; + use Symfony\Component\Translation\MessageSelector; + use Symfony\Component\Translation\Loader\ArrayLoader; + + $translator = new Translator('fr_FR', new MessageSelector()); + $translator->setFallbackLocale('fr'); + $translator->addLoader('array', return new ArrayLoader()); + $translator->addResource('array', array( + 'Hello World!' => 'Bonjour', + ), 'fr'); + + $translator->trans('Hello World!'); Resources --------- +Silex integration: + +https://github.com/fabpot/Silex/blob/master/src/Silex/Provider/TranslationServiceProvider.php + Unit tests: https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Translation diff --git a/src/Symfony/Component/Validator/README.md b/src/Symfony/Component/Validator/README.md index 58934f9f38de..3d16e04b859e 100644 --- a/src/Symfony/Component/Validator/README.md +++ b/src/Symfony/Component/Validator/README.md @@ -1,13 +1,41 @@ Validator Component =================== -This component is based on the JSR-303 Bean Validation specification and enables -specifying validation rules for classes using XML, YAML or annotations, which can -then be checked against instances of these classes. +This component is based on the JSR-303 Bean Validation specification and +enables specifying validation rules for classes using XML, YAML or +annotations, which can then be checked against instances of these classes. + + use Symfony\Component\Validator\Validator; + use Symfony\Component\Validator\Mapping\ClassMetadataFactory; + use Symfony\Component\Validator\Mapping\Loader\StaticMethodLoader; + use Symfony\Component\Validator\ConstraintValidatorFactory; + + $validator = new Validator( + new ClassMetadataFactory(new StaticMethodLoader()), + new ConstraintValidatorFactory() + ); + + $constraint = new Assert\Collection(array( + 'name' => new Assert\Collection(array( + 'first_name' => new Assert\MinLength(101), + 'last_name' => new Assert\MinLength(1), + )), + 'email' => new Assert\Email(), + 'simple' => new Assert\MinLength(102), + 'gender' => new Assert\Choice(array(3, 4)), + 'file' => new Assert\File(), + 'password' => new Assert\MinLength(60), + )); + + $violations = $validator->validateValue($input, $constraint); Resources --------- +Silex integration: + +https://github.com/fabpot/Silex/blob/master/src/Silex/Provider/ValidatorServiceProvider.php + Unit tests: https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Validator diff --git a/src/Symfony/Component/Yaml/README.md b/src/Symfony/Component/Yaml/README.md index c57e97c4a636..f1c512909ad1 100644 --- a/src/Symfony/Component/Yaml/README.md +++ b/src/Symfony/Component/Yaml/README.md @@ -1,17 +1,13 @@ Yaml Component ============== -YAML is a great configuration format. It's the most popular Symfony2 component -right now, because this is probably the only plain-PHP library that implements -most of the YAML 1.2 specification: +YAML implements most of the YAML 1.2 specification. -``` -use Symfony\Component\Yaml\Yaml; + use Symfony\Component\Yaml\Yaml; -$array = Yaml::parse($file); + $array = Yaml::parse($file); -print Yaml::dump($array); -``` + print Yaml::dump($array); Resources ---------