aerni / paparazzi
Generate images of your entries and terms
Requires
- php: ^8.2
- laravel/framework: ^10.0 || ^11.0
- laravel/prompts: *
- spatie/browsershot: ^4.0
- spatie/laravel-ray: ^1.32
- statamic/cms: ^5.0
Requires (Dev)
- orchestra/testbench: ^8.19 || ^9.0
- pestphp/pest: ^2.32
- pestphp/pest-plugin-laravel: ^2.2
This package is auto-updated.
Last update: 2024-10-20 18:10:15 UTC
README
Paparazzi
This addon provides an easy-to-use interface to generate images of your entries and terms. A common use case would be to generate social images for Open Graph and Twitter.
Prerequisite
Paparazzi uses Browsershot to generate the images and requires a working installation of Puppeteer on your server and local machine.
Installation
Install the addon using Composer:
composer require aerni/paparazzi
The config will be automatically published to config/paparazzi.php
as part of the installation process.
Configuring Models
The first thing you should do is to configure your models in config/paparazzi.php
. You can add as many models as you like. The only requirement for a model is the width
and height
. All other configuration options are passed down from the defaults
array. You may override any default value by setting it on the model itself.
'models' => [ 'open_graph' => [ 'width' => 1200, 'height' => 630, ], 'instagram_post' => [ 'width' => 1080, 'height' => 1080, 'extension' => 'jpeg', 'quality' => 80, 'container' => 'instagram', ], ],
Layouts & Templates
Next, you should create your first layout and templates for your models. Use the following commands to do so:
The views will be saved to resources/views/paparazzi
. If you'd like to use another path, you can change it in the config.
Working with models
A model will be created for each template that exists for a given model. The ID of a model will constructed from the model's handle and its template. Let's say you have an open_graph
model with a default
, article
, and video
template. This would result in three models with IDs of open_graph::default
, open_graph::article
, and open_graph::video
.
Use the Model
facade to get a model by its ID:
use Aerni\Paparazzi\Facades\Model; Model::find('open_graph::default');
Alternatively, you can use the model's handle as the method and pass the template as an argument:
Model::openGraph('default');
If you don't pass the template as an argument, you will get the model with the default template as defined in the config('paparazzi.defaults.template')
. If you don't have a template with that name, it will return the first model it can find.
Model::openGraph();
You can also get all the models at once:
Model::all();
Or only a selection of models:
Model::all(['open_graph::defaults', 'twitter::article']);
Or get all the models of a specific type:
Model::allOfType('open_graph');
Generating an image
Now you can simply call the generate()
method on the model:
Model::openGraph()->generate();
Or generate the image in the background by dispatching a job:
Model::openGraph()->dispatch();
If you want the data of an entry or term available in the template, you can add the entry/term with the content()
method:
Model::openGraph()->content($entry)->generate();
Generate the images of all models with the content of an entry.
Model::all()->each->content($entry)->generate();
You can also pass a callback to the generate
or dispatch
method to configure the browsershot instance.
Model::twitter()->generate(fn ($browsershot) => $browsershot->fullPage());
Asset management
The generated images will be saved as a Statamic asset. The asset container, directory, and file reference can be changed in the config.
Variables
You may use a couple of variables to customize the directory and file reference.
File Reference
The reference is used to get the generated images that belong to a model.
'directory' => '{type}/{parent}/{site}/{slug}', 'reference' => '{model}-{layout}-{template}-{parent}-{site}-{slug}',
Previewing Templates
You may preview your templates in the browser according to the following URL schema. The preview is only available in local
environment.
// Schema
/{preview_url}/{model}
// Example
/paparazzi/open_graph
This will return the default template of the open_graph
model. To show a different model, provide the full ID instead:
/paparazzi/open_graph::article
You may also change the layout that is used with the layout
parameter:
/paparazzi/open_graph::article?layout=secondary
To add the content of an entry or term to the rendered template, add the content
query parameter containing the entry's or term's ID.
// Entry ID
/paparazzi/open_graph::article&content=c3d19675-c7b8-49c5-84eb-9c5eb9713644
// Term ID
/paparazzi/open_graph::article&content=cars::audi
Use the optional site
parameter to get the entry or term in a specific localization.
/paparazzi/open_graph::article&content=c3d19675-c7b8-49c5-84eb-9c5eb9713644?site=german
Live Preview
Add a model to the Live Preview of all collections:
public function handle(EntryBlueprintFound $event) { Model::openGraph()->addLivePreviewToCollection(); }
Add a model to the Live Preview of a specific collection:
public function handle(EntryBlueprintFound $event) { Model::openGraph()->addLivePreviewToCollection('pages'); }
Add a model to the Live Preview of multiple selected collection:
public function handle(EntryBlueprintFound $event) { Model::openGraph()->addLivePreviewToCollection(['pages', 'articles']); }
Add a model to the Live Preview of all taxonomies:
public function handle(EntryBlueprintFound $event) { Model::openGraph()->addLivePreviewToTaxonomy(); }
Add a model to the Live Preview of a specific taxonomy:
public function handle(EntryBlueprintFound $event) { Model::openGraph()->addLivePreviewToTaxonomy('categories'); }
Add a model to the Live Preview of multiple selected taxonomies:
public function handle(EntryBlueprintFound $event) { Model::openGraph()->addLivePreviewToTaxonomy(['categories', 'tags']); }
You can also add a model to collections and taxonomies at the same time:
public function handle(TermBlueprintFound $event) { Model::openGraph() ->addLivePreviewToCollection(['pages', 'articles']); ->addLivePreviewToTaxonomy('tags'); }
License
Paparazzi is free to use software but may not be reused in other projects without the express written consent of Michael Aerni.
Credits
Developed by Michael Aerni