Getting Started with the URL Generator Component¶
The way you install and use the URL Generator Component depends on the type of project you are working on:
- In a Symfony Project, the URL Generator Component is installed through Puli’s Symfony Bundle.
- In a PHP Application that will never be a dependency of other Composer packages, the URL Generator Component is installed through Puli’s Composer Plugin.
- In a Composer Package that is a dependency of an application or other packages, the URL Generator Component needs to be installed manually.
In a Symfony Project¶
Important
Before you continue, install the Puli CLI and the Repository Component in your project.
In a Symfony application, the URL Generator Component is installed through Puli’s Symfony Bundle. If you followed Getting Started with the Repository Component, this bundle is already installed in your application.
With Puli’s UrlGenerator
class you can
generate URLs for a Puli path. Let’s print the URL of the
app/Resources/public/images/logo.png
file in a controller:
class PostController
{
public function indexController()
{
$generator = $this->get('puli.url_generator');
echo $generator->generateUrl('/app/public/images/logo.png');
}
}
Tip
In Twig templates you can use the resource_url()
function of
Puli’s Twig Extension. See the
documentation of the extension for more
information.
Before the above code actually works, you need to tell Puli how to generate your
URLs. Add a web server for your web
directory with the Puli CLI:
$ php puli.phar server --add localhost web
In the example, the server is named “localhost”, but you can choose any name you like.
Next, publish the resources under /app/public
to the server:
$ php puli.phar publish /app/public localhost
Now the URL is generated correctly in the template:
<img src="/images/logo.png" />
You can install all public resources in the web
directory with the
publish --install
command:
$ php puli.phar publish --install
Installing /app/public into web via symlink...
In a PHP Application¶
Important
Before you continue, install the Puli CLI and the Repository Component in your project.
In a PHP application, the URL Generator Component is installed through Puli’s Composer Plugin. If you followed Getting Started with the Repository Component, this bundle is already installed in your application.
With Puli’s UrlGenerator
class you can
generate URLs for a Puli path. Use the Puli factory to create the
UrlGenerator
instance:
$factoryClass = PULI_FACTORY_CLASS;
$factory = new $factoryClass();
$repo = $factory->createRepository();
$discovery = $factory->createDiscovery($repo);
$generator = $factory->createUrlGenerator($discovery);
Note
For performance reasons, Puli services such as $factory
or $repo
should be created only once per application. Instead of storing them in
global variables, it is usually nicer to use a Dependency Injection
Container for creating the services on demand. A simple Dependency Injection
Container for small projects is Pimple.
Use the generateUrl()
method to
generate URLs for a resource:
echo $generator->generateUrl('/app/public/images/logo.png');
Tip
Install Puli’s Twig Extension to generate URLs in Twig templates.
This code will echo the URL for the res/public/images/logo.png
file. Before
the code actually works, you need to tell Puli how to generate your URLs. Add a
web server for the document root of your web server with the Puli CLI:
$ php puli.phar server --add localhost public_html
In the example, the server is named “localhost”, but you can choose any name you
like. We assume that the document root of the server is the public_html
directory in your project.
Next, publish the resources under /app/public
to the server:
$ php puli.phar publish /app/public localhost
Now the URL is generated correctly:
echo $generator->generateUrl('/app/public/images/logo.png');
// => /images/logo.png
You can install all public resources in the public_html
directory with the
publish --install
command:
$ php puli.phar publish --install
Installing /app/public into public_html via symlink...
In a Composer Package¶
Important
Before you continue, install the Puli CLI and the Repository Component in your project.
In a Composer package, the URL Generator Component is installed manually. Before
you install the component, set “minimum-stability” to “beta” in
composer.json
:
{
"minimum-stability": "beta"
}
Install the component with Composer:
$ composer require puli/url-generator:^1.0
With Puli’s UrlGenerator
class you can
generate URLs for a Puli path. Use the
generateUrl()
method to
generate URLs for a resource:
echo $generator->generateUrl('/app/public/images/logo.png');
Tip
Install Puli’s Twig Extension to generate URLs in Twig templates.
This code will echo the URL for the res/public/images/logo.png
file.
However, before this code actually works, the application that uses your package
must register a web server and publish your resources there.
You should never create UrlGenerator
instances in a Composer package. Instead, let the application that uses your
package create the URL generator and pass it to your code. This way, every part
of the application uses the same instance and benefits of caching and other
optimizations done internally.
Further Reading¶
- Read Web Server Configuration to learn more about configuring web servers.