diff --git a/book/http_cache.rst b/book/http_cache.rst index 26bd5af042f..2698920121a 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -163,7 +163,7 @@ The caching kernel will immediately act as a reverse proxy - caching responses from your application and returning them to the client. Now that you're using a "proxy", you'll need to configure ``127.0.0.1`` under -the ``trusted_proxies`` configuration (see :ref:`reference `). +the ``trusted_proxies`` configuration (see :ref:`the reference `). Without this, the client's IP address and a few other things won't report correctly. .. tip:: diff --git a/book/service_container.rst b/book/service_container.rst index 41fc7f51d1a..e4334c3943f 100644 --- a/book/service_container.rst +++ b/book/service_container.rst @@ -82,7 +82,7 @@ you need it:: use Acme\HelloBundle\Mailer; $mailer = new Mailer('sendmail'); - $mailer->send('ryan@foobar.net', ...); + $mailer->send('ryan@example.com', ...); This is easy enough. The imaginary ``Mailer`` class allows you to configure the method used to deliver the email messages (e.g. ``sendmail``, ``smtp``, etc). diff --git a/components/class_loader/class_map_generator.rst b/components/class_loader/class_map_generator.rst new file mode 100644 index 00000000000..320a5d2acd4 --- /dev/null +++ b/components/class_loader/class_map_generator.rst @@ -0,0 +1,125 @@ +.. index:: + single: Autoloading; Class Map Generator + single: ClassLoader; Class Map Generator + +The Class Map Generator +======================= + +Loading a class usually is an easy task given the `PSR-0`_ and `PSR-4`_ standards. +Thanks to the Symfony ClassLoader component or the autoloading mechanism provided +by Composer, you don't have to map your class names to actual PHP files manually. +Nowadays, PHP libraries usually come with autoloading support through Composer. + +But from time to time you may have to use a third-party library that comes +without any autoloading support and therefore forces you to load each class +manually. For example, imagine a library with the following directory structure: + +.. code-block:: text + + library/ + ├── bar/ + │   ├── baz/ + │   │   └── Boo.php + │   └── Foo.php + └── foo/ + ├── bar/ + │   └── Foo.php + └── Bar.php + +These files contain the following classes: + +=========================== ================ +File Class name +=========================== ================ +``library/bar/baz/Boo.php`` ``Acme\Bar\Baz`` +--------------------------- ---------------- +``library/bar/Foo.php`` ``Acme\Bar`` +--------------------------- ---------------- +``library/foo/bar/Foo.php`` ``Acme\Foo\Bar`` +--------------------------- ---------------- +``library/foo/Bar.php`` ``Acme\Foo`` +=========================== ================ + +To make your life easier, the ClassLoader component comes with a +:class:`Symfony\\Component\\ClassLoader\\ClassMapGenerator` class that makes +it possible to create a map of class names to files. + +Generating a Class Map +---------------------- + +To generate the class map, simply pass the root directory of your class files +to the :method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::createMap`` +method:: + + use Symfony\Component\ClassLoader\ClassMapGenerator; + + print_r(ClassMapGenerator::createMap(__DIR__.'/library')); + +Given the files and class from the table above, you should see an output like +this: + +.. code-block:: text + + Array + ( + [Acme\Foo] => /var/www/library/foo/Bar.php + [Acme\Foo\Bar] => /var/www/library/foo/bar/Foo.php + [Acme\Bar\Baz] => /var/www/library/bar/baz/Boo.php + [Acme\Bar] => /var/www/library/bar/Foo.php + ) + +Dumping the Class Map +--------------------- + +Writing the class map to the console output is not really sufficient when +it comes to autoloading. Luckily, the ``ClassMapGenerator`` provides the +:method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::dump` method +to save the generated class map to the filesystem:: + + use Symfony\Component\ClassLoader\ClassMapGenerator; + + ClassMapGenerator::dump(__DIR__.'/library', __DIR__.'/class_map.php'); + +This call to ``dump()`` generates the class map and writes it to the ``class_map.php`` +file in the same directory with the following contents:: + + '/var/www/library/foo/Bar.php', + 'Acme\\Foo\\Bar' => '/var/www/library/foo/bar/Foo.php', + 'Acme\\Bar\\Baz' => '/var/www/library/bar/baz/Boo.php', + 'Acme\\Bar' => '/var/www/library/bar/Foo.php', + ); + +Instead of loading each file manually, you'll only have to register the generated +class map with, for example, the :class:`Symfony\\Component\\ClassLoader\\MapClassLoader`:: + + use Symfony\Component\ClassLoader\MapClassLoader; + + $mapping = include __DIR__.'/class_map.php'; + $loader = new MapClassLoader($mapping); + $loader->register(); + + // you can now use the classes: + use Acme\Foo; + + $foo = new Foo(); + + // ... + +.. note:: + + The example assumes that you already have autoloading working (e.g. + through `Composer`_ or one of the other class loaders from the ClassLoader + component. + +Besides dumping the class map for one directory, you can also pass an array +of directories for which to generate the class map (the result actually is +the same as in the example above):: + + use Symfony\Component\ClassLoader\ClassMapGenerator; + + ClassMapGenerator::dump(array(__DIR__.'/library/bar', __DIR__.'/library/foo'), __DIR__.'/class_map.php'); + +.. _`PSR-0`: http://www.php-fig.org/psr/psr-0 +.. _`PSR-4`: http://www.php-fig.org/psr/psr-4 +.. _`Composer`: http://getcomposer.org diff --git a/components/class_loader/index.rst b/components/class_loader/index.rst index de8da86c7c6..9808f59c6d8 100644 --- a/components/class_loader/index.rst +++ b/components/class_loader/index.rst @@ -3,10 +3,11 @@ ClassLoader .. toctree:: :maxdepth: 2 - + introduction class_loader psr4_class_loader map_class_loader cache_class_loader debug_class_loader + class_map_generator diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 5d1c8b31b5e..3e3be050782 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -461,7 +461,7 @@ method:: $command = $application->find('demo:greet'); $commandTester = new CommandTester($command); $commandTester->execute( - array('command' => $command->getName(), 'name' => 'Fabien') + array('command' => $command->getName(), 'name' => 'Fabien', '--iterations' => 5) ); $this->assertRegExp('/Fabien/', $commandTester->getDisplay()); diff --git a/components/map.rst.inc b/components/map.rst.inc index 5d88f3d3ab3..fe243a501b3 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -8,6 +8,7 @@ * :doc:`/components/class_loader/map_class_loader` * :doc:`/components/class_loader/cache_class_loader` * :doc:`/components/class_loader/debug_class_loader` + * :doc:`/components/class_loader/class_map_generator` * :doc:`/components/config/index` diff --git a/cookbook/request/load_balancer_reverse_proxy.rst b/cookbook/request/load_balancer_reverse_proxy.rst index 497d00cdf59..324cbd12838 100644 --- a/cookbook/request/load_balancer_reverse_proxy.rst +++ b/cookbook/request/load_balancer_reverse_proxy.rst @@ -1,5 +1,5 @@ -How to Configure Symfony to Work behind a Load Balancer or Reverse Proxy -======================================================================== +How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy +========================================================================== When you deploy your application, you may be behind a load balancer (e.g. an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for @@ -60,7 +60,8 @@ and which reverse proxy IP addresses will be doing this type of thing: In this example, you're saying that your reverse proxy (or proxies) has the IP address ``192.0.0.1`` or matches the range of IP addresses that use -the CIDR notation ``10.0.0.0/8``. For more details, see :ref:`reference-framework-trusted-proxies`. +the CIDR notation ``10.0.0.0/8``. For more details, see the +:ref:`framework.trusted_proxies ` option. That's it! Symfony will now look for the correct ``X-Forwarded-*`` headers to get information like the client's IP address, host, port and whether or @@ -80,13 +81,13 @@ In this case, you'll need to - *very carefully* - trust *all* proxies. proxies, configure Symfony to *always* trust incoming request. This is done inside of your front controller:: - // web/app.php - // ... + // web/app.php - Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR'))); + // ... + Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR'))); - $response = $kernel->handle($request); - // ... + $response = $kernel->handle($request); + // ... That's it! It's critical that you prevent traffic from all non-trusted sources. If you allow outside traffic, they could "spoof" their true IP address and @@ -97,7 +98,7 @@ My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers Most reverse proxies store information on specific ``X-Forwarded-*`` headers. But if your reverse proxy uses non-standard header names, you can configure -these (:doc:`see reference `. +these (see ":doc:`/components/http_foundation/trusting_proxies`"). The code for doing this will need to live in your front controller (e.g. ``web/app.php``). .. _`security groups`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-elb-security-groups.html