webfactory / slug-validation-bundle
Transparent validation of URL slugs in Symfony applications.
Installs: 7 473
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 8
Forks: 1
Open Issues: 0
Requires
- php: 7.2.*|7.3.*|7.4.*|8.0.*|8.1.*|8.2.*|8.3.*
- symfony/config: ^3.4|^4.0|^5.0|^6.0|^7.0
- symfony/dependency-injection: ^3.4|^4.0|^5.0|^6.0|^7.0
- symfony/event-dispatcher: ^3.4|^4.0|^5.0|^6.0|^7.0
- symfony/http-foundation: ^5.3|^6.0|^7.0
- symfony/http-kernel: ^5.3|^6.0|^7.0
- symfony/routing: ^3.4|^4.0|^5.0|^6.0|^7.0
Requires (Dev)
- phpunit/phpunit: ^8.0|^9.0
This package is auto-updated.
Last update: 2024-10-27 07:59:44 UTC
README
Do not clutter your controller actions with URL slug validation: This Symfony bundle helps to validate object slugs in URLs transparently.
- Checks if a slug is valid (if provided at all)
- Redirects to the URL with the correct slug on failure (for example after a slug change)
Motivation
Handling of URL Slugs is a part of many web applications. Although readable URLs are nice, they usually do not contribute to your main functionality. Instead, slug validation and handling of redirects in case of failure generates a lot of noise in your controller actions, is often cluttered over many parts of the application and makes it harder to see the core problems that are solved.
After facing these problems several times, we decided to create a system that handles slug validation as part of the middleware, that keeps your controller actions clean and lets you concentrate on what is really important: Your domain problems.
Installation
Install the bundle via Composer:
composer require webfactory/slug-validation-bundle
Enable the bundle in your kernel:
<?php
// app/AppKernel.php
public function registerBundles()
{
$bundles = array(
// ...
new \Webfactory\SlugValidationBundle\WebfactorySlugValidationBundle(),
// ...
);
// ...
}
Usage
Prerequisite: In order to be able to use the slug validation provided by this bundle, you have to load your sluggable objects via a param converter. For Doctrine entities Symfony brings this capability out of the box.
Request Your Entity via Param Converter
Declare your object as controller action parameter:
public function myAction(MyEntity $entity)
{
}
When using Doctrine entities, your route parameter entity
must contain the entity ID to make this work.
Implement Sluggable
Provide the hint that the entity has a slug that can be validated by implementing
\Webfactory\SlugValidationBundle\Bridge\SluggableInterface
:
class MyEntity implements SluggableInterface
{
/**
* @return string|null
*/
public function getSlug()
{
return 'my-generated-slug';
}
}
Add Slug Parameter to Routes
Declare a route that contains an entitySlug
parameter and points to your action:
my_entity_route:
path: /entity/{entitySlug}.{entity}
defaults:
_controller: MyBundle:MyController:my
That's it! Whenever a sluggable entity is used together with a slug parameter in a route this bundle will step in and perform a validation. If a slug is invalid, then a redirect to the same route with the corrected slug will be initiated.
Additional Information
Entity and slug parameters are matched by convention: The slug parameter must use the suffix Slug
.
For example the correct parameter name for a blogPost
parameter is blogPostSlug
.
If a route contains a sluggable entity but no slug parameter, then nothing will happen, so the usual Symfony behavior is not changed.
Slug Generation
If you are not sure how to create your slugs, then you might find cocur/slugify useful. A component that generates URL slugs from any string.
Simplified Routing
Passing slug values during route generation can be a tedious and error-prone task. webfactory/object-routing and webfactory/object-routing-bundle can ease that task by defining route construction rules directly with your entity:
/**
* @ObjectRoute(type="my_object_route", name="my_entity_route", params={
* "entity": "id",
* "entitySlug": "slug"
* })
*/
class MyEntity implements SluggableInterface
{
public function getId()
{
// ...
}
public function getSlug()
{
// ...
}
// ...
}
When generating the URL, you don't have to deal with passing these parameters anymore (example in Twig):
{{ object_path('my_object_route', myEntityInstance) }}
Credits, Copyright and License
This project was started at webfactory GmbH, Bonn.
Copyright 2016-2019 webfactory GmbH, Bonn. Code released under the MIT license.