Integrating with Statamic
PicPerf for Statamic addon that automatically reformats, optimizes, and aggressively caches your website’s images using PicPerf.
Getting Started
Section titled “Getting Started”Before installing & using this addon, do the following:
Create an account.
Section titled “Create an account.”After creating an account, you’ll be given a 14-day free trial, but in order keep your images fast & globally available beyond that, upgrade to a regular plan.
Add your domain.
Section titled “Add your domain.”Add your website’s domain inside the PicPerf dashboard.
How to Install
Section titled “How to Install”Search for the PicPerf addon in the Tools > Addons
section of the Statamic control panel and click install, or install it with Composer in the root of your project:
composer require picperf/statamic-picperf
How to Use
Section titled “How to Use”Out of the box, you need to do nothing. The addon will prefix all image URLs with https://picperf.io
, allowing them to be automatically optimized & globally cached. Specifically, only the images in HTML <img>
tags (including responsive images), inline style
attributes, and CSS within <style>
tags will be transformed. Image URLs in separate .css
files or those injected with client-side JavaScript will not be affected.
Disabling Universal Transformation
Section titled “Disabling Universal Transformation”You can opt out of universal image transformation by setting transform_all_markup
to false
inside your config/picperf.php
file. When it’s disabled like this, only content processed with modifiers will be transformed:
<?php
return [ 'transform_all_markup' => false,];
Using a Modifier
Section titled “Using a Modifier”The picperf
modifier will perform same image transformations in a more controlled way. You can use it on single URLs…
{{ featured_image }} <img src="{{ url | picperf }}" alt="{{ alt }}" />{{ /featured_image }}
Or chunks of HTML:
<article> {{ content | picperf }}</article>
Transforming Root-Relative Paths
Section titled “Transforming Root-Relative Paths”By default, the addon won’t transform root-relative images (ex: /some/image.jpg
). However, if you set a host
in your config/picperf.php
file, it’ll be tacked onto those paths so your images can reap the performance gains:
<?php
return [ 'host' => 'https://macarthur.me',];
Adding Images to the Auto-Generated Sitemap
Section titled “Adding Images to the Auto-Generated Sitemap”PicPerf will automatically generate an image sitemap for you based on image requests from the last 90 days.
Enabling Image Sitemap Inclusions
Section titled “Enabling Image Sitemap Inclusions”By default, no images are included in this sitemap. To enable it for all images, set the add_sitemap_path
configuration property to true
:
<?php
return [ // ... other configuration values 'add_sitemap_paths' => true,];
Setting this will add a sitemap_path
query parameter to each image based on the current page path.
Adding Images to Sitemap via Modifier
Section titled “Adding Images to Sitemap via Modifier”If you’d like more control over which images are included in the sitemap, use the add_to_sitemap
parameter on the picperf
modifier:
{{ featured_image }} <img src="{{ url | picperf:add_to_sitemap }}" alt="{{ alt }}" />{{ /featured_image }}
Again, this will cause the sitemap_path
parameter to be appended with the current page.
Auto-Registered Sitemap Endpoint
Section titled “Auto-Registered Sitemap Endpoint”By default, this addon will automatically register an image sitemap route at https://ur-site.com/picperf/sitemap
. All this does is proxy the contents of the auto-generated sitemap at https://picperf.io/sitemap/ur-site.com
. The benefit, however, is that Google will be able to successfully parse it since it’ll be served from your domain.
If you don’t want a sitemap endpoint to be registered, set the register_sitemap
configuration key to false
:
<?php
return [ // ... other configuration values 'register_sitemap' => false,];
Auto-Added Sitemap robots.txt Entry
Section titled “Auto-Added Sitemap robots.txt Entry”On installation, the addon will also add a Sitemap
entry to your robots.txt
. If it was removed and you ever need to add it again, you can run the following command:
php please picperf:register-sitemap
Wanna See the Code?
Section titled “Wanna See the Code?”Here you go: github.com/alexmacarthur/statamic-picperf