https://github.com/umanit/seo-bundle
Seo capabilities for Doctrine entities
https://github.com/umanit/seo-bundle
breadcrumb schema seo-bundle seo-capabilities seo-metadata url-history
Last synced: about 1 month ago
JSON representation
Seo capabilities for Doctrine entities
- Host: GitHub
- URL: https://github.com/umanit/seo-bundle
- Owner: umanit
- Created: 2019-01-18T17:02:31.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-07-10T13:48:26.000Z (11 months ago)
- Last Synced: 2024-10-12T23:46:49.459Z (8 months ago)
- Topics: breadcrumb, schema, seo-bundle, seo-capabilities, seo-metadata, url-history
- Language: PHP
- Size: 327 KB
- Stars: 5
- Watchers: 6
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Umanit Seo Bundle
This bundle adds SEO capabilities for any model entities.
## Features
- [x] 301 Redirects when accessing an old URL
- [x] SEO Metadata (title and description)
- [x] Canonical URL
- [x] Schema.org
- [x] Breadcrumb
- [ ] Sitemap
## Installation
`$ composer require umanit/seo-bundle`
## Configuration
The template needs to be declared in your Twig configuration, **before** other templates. You must choose one between:
```yaml
twig:
# ...
form_themes:
- '@UmanitSeo/sylius/form/fields.html.twig'
# OR
- '@UmanitSeo/sonata/form/fields.html.twig'
- ...
```
You can configure your bundle further by creating a `umanit_seo.yaml` configuration file. Here is the default
configuration provided by the bundle:
```yaml
# Default configuration for extension with alias: "umanit_seo"
umanit_seo:
# Historize URLs of entities which implements HistorizableUrlModelInterface
url_historization:
enabled: true
# Redirect code used by UrlRedirectorSubscriber
redirect_code: 301
# Cache service used to store entities dependencies. **MUST** implements \Symfony\Contracts\Cache\CacheInterface
cache_service: cache.app
# Defines the default templates used to render breadcrumbs
templates:
breadcrumb_json_ld: '@UmanitSeo/breadcrumb/breadcrumb.json-ld.html.twig'
breadcrumb_microdata: '@UmanitSeo/breadcrumb/breadcrumb.microdata.html.twig'
breadcrumb_rdfa: '@UmanitSeo/breadcrumb/breadcrumb.rdfa.html.twig'
metadata:
form_type:
# Automaticaly add a SeoMetadataType on FormType which handled an entity which implements HasSeoMetadataInterface
add_seo_metadata_type: true
# FQCN of the FormType used to renders SEO Metadata fields
class_fqcn: Umanit\SeoBundle\Form\Type\SeoMetadataType
# Injects Google Code Prettify when rendering breadcrumb and schema.org in FormType.
inject_code_prettify: true
default_title: 'Umanit Seo - Customize this default title to your needs.'
title_prefix: ''
title_suffix: ''
default_description: 'Umanit Seo - Customize this default description to your needs.'
```
## Usage
1. [Basic Usage](#basic-usage)
1. [Seo Metadata](#seo-metadata)
1. [Schema.org](#schemaorg-implementation)
1. [Breadcrumb](#breadcrumb)
1. [Enabling 301 redirects](#enabling-301-redirects)
1. [Twig functions reference](#twig-functions-reference)
1. [Protips](#protips)
### Basic usage
In order to function properly, SeoBundle must be able to generate a URL for a given entity. To do so, the
`umanit_seo.routable` service uses handlers to process the entity.
A handler is a service which implements `Umanit\SeoBundle\Handler\Routable\RoutableHandlerInterface`. A `supports`
method indicated if the service can handle the given entity and a `process` method do the job by returning a
`Umanit\SeoBundle\Model\Route` object.
The `Umanit\SeoBundle\Model\Route` object has a `name` attribute, which is the name of the route used to access the
entity and a `parameters` attribute used to build the route.
**You must implement the interface `Umanit\SeoBundle\Model\RoutableModelInterface` on your entity and create a handler
to process it.**
```php
$entity->getSlug()]);
}
}
```
SeoBundle will now be able to generate a URL from the entity. If you ever change the slug of a page, the old URL will be
redirected to the new one.
If you wanted to generate the URL by yourself you would have done something like the following example:
```twig
{{ path('app_page_show', { 'slug': my_page.slug }) }}"
```
You can now do like so:
```twig
{{ path(my_page) }}
```
_**Note:** You can use the `canonical()` function without passing it an entity, SeoBundle will automatically resolve the
entity associated to the current accessed route and generate the url from it._
Usually, you'll want to use the `canonical()` function directly within your main layout.
### Seo Metadata
Use the `seo_metadata(your_entity)` twig function in your templates.
SeoBundle will automatically find the most pertinent fields in your entity to deduct title and description.
Again, `seo_metadata()` can be used without passing it any entity.
#### Administrating metadata
In order to administrate Seo Metadata, you'll need again to tune-up your entity.
Make your entity implement the `HasSeoMetadataInterface` and use the `SeoMetadataTrait`
```php
name($entity->getName())
->url($entity->getSlug())
->contactPoint(Schema::contactPoint()->areaServed('Worldwide'))
;
}
}
```
Next, add the twig function `seo_schema_org()` at the bottom of your layout.
The function will format and display the json schema of the current entity as you defined it.
```html
{
"@context": "https:\/\/schema.org",
"@type": "MensClothingStore",
"name": "Test",
"email": "[email protected]",
"contactPoint": {
"@type": "ContactPoint",
"areaServed": "Worldwide"
}
}
```
### Breadcrumb
You can easily generate your breadcrumb in 3 different formats; `Microdata`, `RDFa` or `JSON-LD` as described by
[the specification](https://schema.org/BreadcrumbList). To do so, the `umanit_seo.breadcrumbable` service uses handlers
to process the entity.
A handler is a service which implements `Umanit\SeoBundle\Handler\Breadcrumbable\BreadcrumbableHandlerInterface`. A
`supports` method indicated if the service can handle the given entity and a `process` method do the job by returning a
`Umanit\SeoBundle\Model\Breadcrumb` object.
The `Umanit\SeoBundle\Model\Breadcrumb` obect has a `format` attribute, which is one of the previously mentionned and a
`items` attributes which is an array of `Umanit\SeoBundle\Model\BreadcrumbItem`. Each `BreadcrumbItem` has a `label`
attribute and an optionnal `url` attribute.
**You must implement the interface `Umanit\SeoBundle\Model\BreadcrumbableModelInterface` on your entity and create a
handler to process it.**
```php
setItems([
new BreadcrumbItem('Homepage', '/'),
new BreadcrumbItem(
$entity->getCategory()->getName(),
$this->router->generate('app_page_category_show', ['slug' => $entity->getCategory()->getSlug()])
),
new BreadcrumbItem($entity->getName()),
]);
return $breadcrumb;
}
}
```
_**Note:** If the processed entity implements the `RoutableModelInterface`, you can omit the `url` attribute to let the
service `umanit_seo.routable` generate it for you._
You can now use the twig function `seo_breadcrumb()` like the following examples:
```twig
{{ seo_breadcrumb() }} {# Will generate the breadcrumb from the current entity using microdata format #}
{{ seo_breadcrumb(entity=my_entity, format='json-ld') }} {# Will generate the breadcrumb from my_entity using json-ld format #}
{{ seo_breadcrumb(format='rdfa') }} {# Will generate the breadcrumb from the current entity using rdfa format #}
```
### Enabling 301 redirects
In order to enable URL history and 301 redirects on an entity, ensure the configuration
`umanit_seo.url_historization.enabled` is active (yes by default) then implement the interface
`Umanit\SeoBundle\Model\HistorizableUrlModelInterface` and use the trait
`Umanit\SeoBundle\Doctrine\Model\HistorizableUrlTrait`.
```php