Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marcin-jozwikowski/easy-admin-pretty-urls
Pretty REST-like URLs in EasyAdmin
https://github.com/marcin-jozwikowski/easy-admin-pretty-urls
Last synced: 3 months ago
JSON representation
Pretty REST-like URLs in EasyAdmin
- Host: GitHub
- URL: https://github.com/marcin-jozwikowski/easy-admin-pretty-urls
- Owner: marcin-jozwikowski
- License: mit
- Created: 2022-12-23T10:15:28.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-17T16:20:55.000Z (5 months ago)
- Last Synced: 2024-07-18T22:17:27.997Z (4 months ago)
- Language: PHP
- Size: 132 KB
- Stars: 26
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# EasyAdmin Pretty URLs
### Symfony Bundle that introduces customizable routes to EasyAdmin
## Example
Turn
```
http://ea-demo.loc/en/easyadmin?crudAction=index&crudControllerFqcn=App%5CController%5CEasyAdmin%5CPostCrudController
```
into
```
http://ea-demo.loc/en/post_crud/index
```
---
## Instalation
1. Install the bundle by running
```shell
composer require marcin-jozwikowski/easy-admin-pretty-urls
```
1. Enable the bundle by adding it to your `config/bundles.php` if not enabled automatically
```php
return [
// ...
MarcinJozwikowski\EasyAdminPrettyUrls\EasyAdminPrettyUrlsBundle::class => ['all' => true],
];
```
1. Add a routes set pointing to a directory containing your Controllers
```yaml
pretty_routes_name:
resource: 'src/Controller'
type: 'pretty_routes'
```
The `resource` is a directory path relative to your projects root directory. Type must always equal to `pretty_routes`. See [_Fine-tuning_ / _Define routes manually_](#Fine-tuning) section to learn how this step can be ommitted.
Other routing structures can be utilized as well, for example:
```yaml
pretty_routes:
resource: 'src/Controller'
type: 'pretty_routes'
prefix: /{_locale}
requirements:
_locale: '%app_locales%'
defaults:
_locale: '%locale%'
```
1. Make your main DashboardController extend `\MarcinJozwikowski\EasyAdminPrettyUrls\Controller\PrettyDashboardController` or manually override the a default template like so:
```php
public function configureCrud(): Crud
{
return parent::configureCrud()
->overrideTemplate('layout', '@EasyAdminPrettyUrls/layout.html.twig')
->overrideTemplate('crud/field/association', '@EasyAdminPrettyUrls/crud/field/association.html.twig');
}
```
## Configuration
The following parameters are in use:
| Parameter | Default value | Description |
|----------------------|------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| `route_prefix` | `"pretty"` | First part of route name |
| `default_dashboard` | `"App\Controller\EasyAdmin\DashboardController::index"` | Default controller action to invoke if not specified in attributes |
| `default_actions` | `["index", "new", "detail", "edit", "delete", "batchDelete", "renderFilters", "autocomplete"]` | Default set of actions to build routes against |
| `include_menu_index` | `false` | Should menu index be included in path |
| `drop_entity_fqcn` | `false` | Should `entityFqcn` be removed from the URLs |
To change the default values set the parameter in your `services.yaml`
```yaml
parameters:
easy_admin_pretty_urls.: ''
```
Or create a `config/packages/easyadmin_pretty_urls.yaml` file with
```yaml
easy_admin_pretty_urls:
: ''
```
## Twig
There are one function, and one filter being registered by a Twig extension in this bundle:
* `pretty_urls_include_menu_index()` Function returns the `include_menu_index` value from Configuration
* `|pretty_urls_remove_actions` Filter removed the unnecessary query elements from the URL string
## Fine-tuning
* ### Define custom URL path
By default, the URL is created as `/`.
To change that behavior specify `path` value in `PrettyRoutesController` attribute for the whole controller, and/or
in `PrettyRoutesAction` attribute for the specific action.
The following configuration will result in the action URL of `special/list` instead of the default `any_fancy/index`.
```php
#[PrettyRoutesController(path: 'special')]
class AnyFancyController {
#[PrettyRoutesAction(path: 'list')]
public function index() {
// ....
}
}
```
* ### Putting entityID in the path
With a custom path defined in `#PrettyRoutesAction` attribute, it is possible to include the entityID in the path.
To achieve it, simple add `{entityId?0}` to the `path` argument i.e.
```php
#[PrettyRoutesAction(path: 'modify/{entityId?0}')]
public function edit(AdminContext $context)
{
return parent::edit($context);
}
```
Due to the way form actions are generated by EasyAdmin it is necessary to specify a default value for the parameter in the path.
It does not have to be `0` but keep in mind that setting it to an existing ID will make the application unusable.
* ### Select actions to create routes for
By default, pretty routes are generated for `index`, `new`, `detail`, `edit`, `delete`, `batchDelete`, `renderFilters`, and `autocomplete` actions.
To change them globally set a proper [_configuration_](#Configuration) value.
For a single-controller change add a `PrettyRoutesController` attribute to the controller and name the actions you want to have pretty routes for, in `actions` parameter.
```php
#[PrettyRoutesController(actions: ['index', 'foo', 'bar'])]
class AnyFancyController {
// ...
}
/**
* You can also (optionally) specify your own dashboard controller if you're using more than one in your project.
* This will avoid to have an incorrect sidebar/user menu by addressing the request to the right dashboard controller
*/
#[PrettyRoutesController(actions: ['index', 'foo', 'bar'], dasboard: YourCrudController::class . '::yourCrudAction')]
class AnyFancyController {
// ...
}
```
You can also just add your custom actions to the default list by specifying `customActions` in `PrettyRoutesController` attribute.
```php
#[PrettyRoutesController(customActions: ['foo', 'bar'])]
class AnyFancyController {
...
```
* ### Define routes manually
Instead of defining a `pretty_routes` routes to automatically parse all classes in a directory you can create routes that will replace your default EasyAdmin CRUD actions.
```yaml
pretty_foobar_index:
path: /foobar-url
controller: \App\Controller\EasyAdmin\DashboardController::index
defaults:
crudControllerFqcn: \App\Controller\FoobarCrudController
crudAction: index
```
* `controller` value must point to your projects DashboardController
* `defaults` `crudControllerFqcn` and `crudAction` must point to your target CRUD controller and its action.
* `path` can be anything of your choosing
* Route name must match the pattern `__` with
* `` equal to `crudAction` value from the defaults
* `` being the target controller class name (not FQCN - just the last part) stripped of `Controller`, written in _snake_case_
* `` is set to `pretty` by default. See Configuration to ways to change it.
* When routes are defined manually the _Installation step 3_ is not required.
You can generate a YAML routes configuration for existing controllers for further manual modifications by running
```shell
bin/console pretty-routes:dump
```
## Troubleshooting
* ### Routes not working
If your routes are still not generated despite being added, check your logs for `'Pretty route not found'` with `debug` level. Those will list all the EasyAdmin routes that did not have their pretty counterparts.
Most probably, there's some naming mismatch.
* ### Checking the Resource parsing results
To see what is the outcome of parsing a `pretty_routes` Resource run the following command:
```shell
bin/console pretty-routes:debug
```