diogo/symfony
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

merged branch lsmith77/component_readmes (PR #2561)

Browse Source 
Commits
-------

1e370d7 typo fix
93d8d44 added some more infos about Config
27efd59 added READMEs for the bridges
34fc866 cosmetic tweaks
d6af3f1 fixed README for Console
6a72b8c added basic README files for all components

Discussion
----------

added basic README files for all components and bridges

heavily based on http://fabien.potencier.org/article/49/what-is-symfony2 and the official Symfony2 documentation

---------------------------------------------------------------------------

by jmikola at 2011/11/03 13:36:07 -0700

Great work. For syntax highlighting on the PHP snippets, you could add "php" after the three backticks.

---------------------------------------------------------------------------

by lsmith77 at 2011/11/03 13:41:29 -0700

done

---------------------------------------------------------------------------

by stealth35 at 2011/11/03 13:49:31 -0700

Nice job, but you also need to add `<?php`

ex :

``` php
<?php
use Symfony\Component\DomCrawler\Crawler;

$crawler = new Crawler();
$crawler->addContent('<html><body><p>Hello World!</p></body></html>');

print $crawler->filter('body > p')->text();
```

---------------------------------------------------------------------------

by lsmith77 at 2011/11/03 13:56:57 -0700

done

---------------------------------------------------------------------------

by ericclemmons at 2011/11/03 19:57:57 -0700

@lsmith77 Well done!  This makes consumption of individual components that much easier, *especially* now that `composer.json` files have been added.

---------------------------------------------------------------------------

by lsmith77 at 2011/11/04 01:18:23 -0700

ok .. fixed the issues you mentioned @fabpot

---------------------------------------------------------------------------

by lsmith77 at 2011/11/11 15:00:27 -0800

@fabpot anything else left? seems like an easy merge .. and imho there is considerable benefit for our efforts to spread the word about the components with this PR merged.

---------------------------------------------------------------------------

by drak at 2011/11/11 18:54:13 -0800

You know, it might be a nice idea to put a link to the documentation for each component if there is some at symfony.com

---------------------------------------------------------------------------

by lsmith77 at 2011/11/12 00:59:14 -0800

i did that in some. but i might have missed a few places.
On 12.11.2011, at 03:54, Drak <reply@reply.github.com> wrote:

> You know, it might be a nice idea to put a link to the documentation for each component if there is some at symfony.com
>
> ---
> Reply to this email directly or view it on GitHub:
> https://github.com/symfony/symfony/pull/2561#issuecomment-2715762

---------------------------------------------------------------------------

by breerly at 2011/11/21 10:28:36 -0800

Pretty excited with this.

---------------------------------------------------------------------------

by dbu at 2011/11/24 00:02:50 -0800

is there anything we can help with to make this ready to be merged?

---------------------------------------------------------------------------

by lsmith77 at 2011/12/18 02:39:23 -0800

@fabpot: seriously .. if you are not going to deliver something "better" and don't provide a reason what is wrong with this .. then its beyond frustrating. i obviously do not claim that these README's are perfect (and certainly still no replacement for proper documentation), but I do claim that in their current form they are a radical step forward to potential users of the Symfony2 components.
This commit is contained in:
Fabien Potencier 2011-12-18 12:42:02 +01:00
commit 0f2caf1106
25 changed files with 647 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
src/Symfony/Bridge/Doctrine/README.md Normal file
View File

@ -0,0 +1,11 @@
Doctrine Bridge
===============
Provides integration for Doctrine with various Symfony2 components.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Bridge/Doctrine

11
src/Symfony/Bridge/Monolog/README.md Normal file
View File

@ -0,0 +1,11 @@
Monolog Bridge
==============
Provides integration for Monolog with various Symfony2 components.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Bridge/Monolog

11
src/Symfony/Bridge/Twig/README.md Normal file
View File

@ -0,0 +1,11 @@
Twig Bridge
===========
Provides integration for Twig with various Symfony2 components.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Bridge/Twig

11
src/Symfony/Component/BrowserKit/README.md Normal file
View File

@ -0,0 +1,11 @@
BrowserKit Component
====================
This component provides classes to simulate a browser for testing.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/BrowserKit

41
src/Symfony/Component/ClassLoader/README.md Normal file
View File

@ -0,0 +1,41 @@
ClassLoader Component
=====================
The ClassLoader component provides an autoloader that implements the PSR-0 standard
(which is a standard way to autoload namespaced classes as available in PHP 5.3).
It is also able to load classes that use the PEAR naming convention. It is really
flexible as it can look for classes in different directories based on a sub-namespace.
You can even give more than one directory for one namespace:
```
require_once __DIR__.'/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
use Symfony\Component\ClassLoader\UniversalClassLoader;
$loader = new UniversalClassLoader();
$loader->registerNamespaces(array(
'Symfony' => array(__DIR__.'/src', __DIR__.'/symfony/src'),
'Doctrine\\Common' => __DIR__.'/vendor/doctrine-common/lib',
'Doctrine\\DBAL' => __DIR__.'/vendor/doctrine-dbal/lib',
'Doctrine' => __DIR__.'/vendor/doctrine/lib',
'Monolog' => __DIR__.'/vendor/monolog/src',
));
$loader->registerPrefixes(array(
'Twig_' => __DIR__.'/vendor/twig/lib',
));
$loader->register();
```
Most of the time, the Symfony2 ClassLoader is all you need to autoload all your project classes.
And for better performance, you can use an APC cached version of the universal class loader or
the map class loader.
Furthermore it provides tools to aggregate classes into a single file, which is especially
useful to improve performance on servers that do not provide byte caches.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/ClassLoader

14
src/Symfony/Component/Config/README.md Normal file
View File

@ -0,0 +1,14 @@
Config Component
================
This component provides infrastructure from loading configurations from different
data sources and optionally monitoring these data sources for changes. There are
additional tools for validating, normalizing and handling of defaults that can
optionally be used to convert from different formats to arrays.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Config

44
src/Symfony/Component/Console/README.md Normal file
View File

@ -0,0 +1,44 @@
Console Component
=================
Even if we are talking about a web framework, having some tools to manage
your project from the command line is nice. In Symfony2, we use the console
to generate CRUDs, update the database schema, etc. It's not required, but
it is really convenient and it can boost your productivity a lot.
This example shows how to create a command line tool very easily:
```
use Symfony\Component\Console\Application;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
$console = new Application();
$console
->register('ls')
->setDefinition(array(
new InputArgument('dir', InputArgument::REQUIRED, 'Directory name'),
))
->setDescription('Displays the files in the given directory')
->setCode(function (InputInterface $input, OutputInterface $output) {
$dir = $input->getArgument('dir');
$output->writeln(sprintf('Dir listing for <info>%s</info>', $dir));
})
;
$console->run();
```
With only 10 lines of code or so, you have access to a lot of features like output
coloring, input and output abstractions (so that you can easily unit-test your
commands), validation, automatic help messages, and a lot more. It's really powerful.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Console

4
src/Symfony/Component/CssSelector/README
View File

@ -1,4 +0,0 @@
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

38
src/Symfony/Component/CssSelector/README.md Normal file
View File

@ -0,0 +1,38 @@
CssSelector Component
=====================
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
Using CSS selectors is far easier than using XPath.
Its only goal is to convert a CSS selector to its XPath equivalent:
```
use Symfony\Component\CssSelector\CssSelector;
print CssSelector::toXPath('div.item > h4 > a');
```
That way, you can just use CSS Selectors with the DomCrawler instead of XPath:
```
use Symfony\Component\DomCrawler\Crawler;
$crawler = new Crawler();
$crawler->addContent('<html><body><p>Hello World!</p></body></html>');
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.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/CssSelector

26
src/Symfony/Component/DependencyInjection/README.md Normal file
View File

@ -0,0 +1,26 @@
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');
```
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/DependencyInjection

21
src/Symfony/Component/DomCrawler/README.md Normal file
View File

@ -0,0 +1,21 @@
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:
```
use Symfony\Component\DomCrawler\Crawler;
$crawler = new Crawler();
$crawler->addContent('<html><body><p>Hello World!</p></body></html>');
print $crawler->filterXPath('descendant-or-self::body/p')->text();
```
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/DomCrawler

22
src/Symfony/Component/EventDispatcher/README.md Normal file
View File

@ -0,0 +1,22 @@
EventDispatcher Component
=========================
```
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\EventDispatcher\Event;
$dispatcher = new EventDispatcher();
$dispatcher->addListener('event_name', function (Event $event) {
// ...
});
$dispatcher->dispatch('event_name');
```
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/EventDispatcher

43
src/Symfony/Component/Finder/README.md Normal file
View File

@ -0,0 +1,43 @@
Finder Component
================
The Finder provides a very convenient and nice fluent interface to find files
and directories on the filesystem:
```
use Symfony\Component\Finder\Finder;
$finder = new Finder();
$iterator = $finder
->files()
->name('*.php')
->depth(0)
->size('>= 1K')
->in(__DIR__);
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");
$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
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Finder

17
src/Symfony/Component/Form/README.md Normal file
View File

@ -0,0 +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.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Form
Documentation:
http://symfony.com/doc/2.0/book/forms.html

38
src/Symfony/Component/HttpFoundation/README.md Normal file
View File

@ -0,0 +1,38 @@
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, ...
In this example, we get a Request object from the current PHP global variables:
```
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();
```
And here is how to create and send a Response:
```
$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.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/HttpFoundation

93
src/Symfony/Component/HttpKernel/README.md Normal file
View File

@ -0,0 +1,93 @@
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')));
}
)));
$request = Request::createFromGlobals();
$context = new RequestContext();
$context->fromRequest($request);
$matcher = new UrlMatcher($routes, $context);
$dispatcher = new EventDispatcher();
$dispatcher->addSubscriber(new RouterListener($matcher));
$resolver = new ControllerResolver();
$kernel = new HttpKernel($dispatcher, $resolver);
$kernel->handle($request)->send();
```
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');
$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);
}));
```
I can continue on and on but I think you get the point.
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
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/HttpKernel

23
src/Symfony/Component/Locale/README.md Normal file
View File

@ -0,0 +1,23 @@
Locale Component
================
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.
```
// 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'));
}
```
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Locale

47
src/Symfony/Component/Process/README.md Normal file
View File

@ -0,0 +1,47 @@
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:
```
use Symfony\Component\Process\Process;
$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:
```
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;
}
});
```
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.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Process

33
src/Symfony/Component/Routing/README.md Normal file
View File

@ -0,0 +1,33 @@
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:
```
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;
$routes = new RouteCollection();
$routes->add('hello', new Route('/hello', array('controller' => 'foo')));
$context = new RequestContext();
// this is optional and can be done without a Request instance
$context->fromRequest(Request::createFromGlobals());
$matcher = new UrlMatcher($routes, $context);
$parameters = $matcher->match('/hello');
```
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Routing

18
src/Symfony/Component/Security/README.md Normal file
View File

@ -0,0 +1,18 @@
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.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Security
Documentation:
http://symfony.com/doc/2.0/book/security.html

13
src/Symfony/Component/Serializer/README.md Normal file
View File

@ -0,0 +1,13 @@
Serializer Component
====================
With the Serializer component its possible to handle serializing data structures,
including object graphs, into array structures or other formats like XML and JSON.
It can also handle deserializing XML and JSON back to object graphs.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Serializer

14
src/Symfony/Component/Templating/README.md Normal file
View File

@ -0,0 +1,14 @@
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.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Templating

16
src/Symfony/Component/Translation/README.md Normal file
View File

@ -0,0 +1,16 @@
Translation Component
=====================
This component provides tools for loading translation files and generating translated
strings from these including support for pluralization.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Translation
Documentation:
http://symfony.com/doc/2.0/book/translation.html

21
src/Symfony/Component/Validator/README.md Normal file
View File

@ -0,0 +1,21 @@
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.
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Validator
Documentation:
http://symfony.com/doc/2.0/book/validation.html
JSR-303 Specification:
http://jcp.org/en/jsr/detail?id=303

21
src/Symfony/Component/Yaml/README.md Normal file
View File

@ -0,0 +1,21 @@
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:
```
use Symfony\Component\Yaml\Yaml;
$array = Yaml::parse($file);
print Yaml::dump($array);
```
Resources
---------
Unit tests:
https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/Yaml