{"id":28656087,"url":"https://github.com/offline-gmbh/oc-responsive-images-plugin","last_synced_at":"2025-09-03T13:07:10.941Z","repository":{"id":37743300,"uuid":"47880923","full_name":"OFFLINE-GmbH/oc-responsive-images-plugin","owner":"OFFLINE-GmbH","description":"Adds reponsive images capabilities to October CMS","archived":false,"fork":false,"pushed_at":"2025-01-31T13:58:38.000Z","size":208,"stargazers_count":44,"open_issues_count":23,"forks_count":26,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2025-06-09T23:32:23.943Z","etag":null,"topics":["hacktoberfest","octobercms","octobercms-plugin","responsive"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OFFLINE-GmbH.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-12T14:19:10.000Z","updated_at":"2025-01-31T13:58:29.000Z","dependencies_parsed_at":"2023-12-20T14:57:49.045Z","dependency_job_id":"bd773627-99d1-4088-b83f-b9d7745dfce8","html_url":"https://github.com/OFFLINE-GmbH/oc-responsive-images-plugin","commit_stats":{"total_commits":174,"total_committers":21,"mean_commits":8.285714285714286,"dds":"0.49425287356321834","last_synced_commit":"14ae51f2f3c2b2851deb5aef629a501e860b1efd"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"purl":"pkg:github/OFFLINE-GmbH/oc-responsive-images-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-responsive-images-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-responsive-images-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-responsive-images-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-responsive-images-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OFFLINE-GmbH","download_url":"https://codeload.github.com/OFFLINE-GmbH/oc-responsive-images-plugin/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-responsive-images-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259606992,"owners_count":22883565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","octobercms","octobercms-plugin","responsive"],"created_at":"2025-06-13T08:10:15.218Z","updated_at":"2025-06-13T08:10:16.725Z","avatar_url":"https://github.com/OFFLINE-GmbH.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ResponsiveImages Plugin for October CMS\n\nAutomatically generate and serve images for your visitor's viewport size without changing your theme!\n\n\n## Features\n\n* [Responsive images](#responsive-images)\n* [WebP conversion](#webp-conversion)\n* [Focuspoint](#focuspoint)\n* [Inline SVG helper function](#inlining-svg-images)\n\n## Responsive images\n\n### How it works\n\nThis plugin provides a middleware that adds `srcset` and `sizes` attributes to all locally served images in your html\n response.\n\nIt turns this\n\n```html\n\u003cimg width=\"500\" src=\"/storage/app/media/image.jpg\"\u003e\n```\n\ninto this\n\n```html\n\u003cimg width=\"500\" src=\"/storage/app/media/image.jpg\" srcset=\"/storage/temp/public/be7/4d6/0cc/image__400.jpg 400w, /storage/temp/public/be7/4d6/0cc/image__768.jpg 768w, /storage/temp/public/be7/4d6/0cc/image__1024.jpg 1024w\" sizes=\"(max-width: 500px) 100vw, 500px\"\u003e\n```\n\nIt automatically creates resized copies of the image and serves the most fitting one to your visitor.\n\nAll image copies are saved in your public temp path. Remote file systems are currently untested.\n\nThe images are generated on the first page load. Depending on the source image size this may take a few seconds.\nSubsequent page loads will be faster since the images are only resized once.\n\n### Configuration\n\nThree image sizes are created by default: 400, 768 and 1024 pixels.\n\nYou can change these values by changing the settings in the backend.\n\n#### Alternative `src` and `srcset` attributes\n\nIf you want to use an alternative `src` attribute you can change this via the backend settings page.\n\nThis is useful if you are using a plugin like [jQuery.lazyLoad](http://www.appelsiini.net/projects/lazyload) where the image\n is initially linked via a `data-original` attribute.\n\n If your plugin requires an alternative srcset attribute (like [verlok/LazyLoad](https://github.com/verlok/lazyload)) this can also be specified via the backend settings.\n\n\n#### Global `class` attributes\n\nIf you want to add a class to every processed image you can configure this via the backend settings.\n\nThis is useful if you want to add Bootstrap's `img-responsive` class to all images on your website.\n\n#### Pre-generate images\n\nYou can use the `php artisan responsive-images:generate` command to pre-generate responsive images. The command uses\nOctober's `pages.menuitem.*` events to build a list of all available URLs and pre-generates all images used on these\npages.\n\n#### Test results\n\nI have tested this plugin on a page with 20 hd wallpapers from pixabay.\n\n| Viewport width | Transferred file size |\n| -------------: | ---------------------:|\n|        1920 px |               21.8 MB |\n|        1024 px |                3.1 MB |\n|         768 px |                2.0 MB |\n|         400 px |                0.8 MB |\n\n\n## Opt-out of processing\n\nIf for any reason you want an `img` tag to be completely ignored by this plugin, simply\nadd the `data-responsive=\"ignore\"` attribute to your tag:\n\n```html\n\u003cimg src=\"dont-process-this.jpg\" data-responsive=\"ignore\" alt=\"\"\u003e\n```\n\n## Delete resized images\n\nUse the `php artisan responsive-images:clear` command to delete all\nresized images. The next time a page/image is requested, the resized\ncopies will be created again.\n\n## WebP conversion\n\nThis plugin provides an option to serve WebP images if the visiting Browser signals support for it.\n\nEnable the WebP conversion in the backend settings. Enabling this option will add a rule\nto your `.htaccess` file, that checks for a `{filename}.{extension}.webp` image for every request\nand serves it to the client, if available.\n\n### Console command to convert images to WebP\n\nThe plugin includes a handy console command that you can run in a cronjob that iterates\nthrough your storage directories and converts images to WebP:\n\n```\nphp artisan responsive-images:convert --include=storage/app\n```\n\nThis command requires the `cwebp` to be available on your server. You can [download it for your OS](https://developers.google.com/speed/webp/download)\nand provide the path to the binary using the `--converter-path` option.\n\n\n#### Conversion errors\n\nYou can find a log of failed image conversions in the `offline_responsiveimages_inconvertibles` table.\nIf the conversion for a file failed, it will be logged in this table. The conversion will not be\nretried for files that failed before. To force a retry, remove the file from the table table\nand run the conversion command again.\n\n\n### Support for other servers than Apache\n\n**If you do not use Apache**, you have to configure your server to do the following:\n\n1. Check if `image/webp` is present in the `Accepts` http header\n1. Check if the requested image ends in `jp(e)g` or `png`\n1. Check if the requested image + a `.webp` exists\n1. *If it does*, serve it\n\n### Apache + .htaccess\n\nIf you are using Apache with `mod_rewrite` enabled, you do not have to do anything manually.\nThe plugin [will patch your `.htaccess` file](views/webp-rewrite.htm) if WebP support gets enabled.\n\n### Nginx\n\nIf you are using Nginx to serve your October website, you have to modify your server configuration **manually**.\n\nThe following example should give you a good starting point.\n\n```nginx\nuser www-data;\n\nhttp {\n  sendfile on;\n  tcp_nopush on;\n  tcp_nodelay on;\n\n  include /etc/nginx/mime.types;\n  default_type application/octet-stream;\n\n  gzip on;\n  gzip_disable \"msie6\";\n\n  map $http_accept $webp_suffix {\n    default   \"\";\n    \"~*webp\"  \".webp\";\n  }\n\n  # ...\n\n  server {\n    charset utf-8;\n    listen 80;\n\n    server_name localhost;\n    root /var/www/html;\n    index index.php;\n\n    location ~ \\.(jpe?g|png)$ {\n\tadd_header Vary Accept;\n        try_files $uri$webp_suffix $uri/;\n    }\n\n    # ...\n  }\n}\n```\n\nYour `mime.types` file should additionally list the webp mime type:\n\n```types\nimage/webp  webp;\n```\n\n### Other servers\n\nWe did not invest in the proper WebP detection configuration for other server software.\nBased on the `.htaccess` example above and the [webp-detect](https://github.com/igrigorik/webp-detect)\nrepo you should be able to figure out what config is needed.\n\nIf you have a working example please add it via a PR to this README!\n\n### Custom base directory path\n\nIf your application directory is located in a special location, you can set the\n`RESPONSIVE_IMAGES_BASE_DIR` environment variable to [change the source path](./webp.php#29).\n\n```htaccess\n\u003cIfModule mod_setenvif.c\u003e\n    SetEnv RESPONSIVE_IMAGES_BASE_DIR /path/to/your/dir\n\u003c/IfModule\u003e\n```\n\n## Focuspoint\n\nThis feature has two components to it:\n\n#### Backend\n\nIn the backend, the file upload widget is extended with a simple focus point selector.\n\nTo enable this extension simply set `focuspoint: true` to any fileupload widget in your\nplugin's `fields.yaml`. This feature is off by default.\n\nOnce it is enabled you can click on an uploaded image to select the focus point.\n\n```yaml\nfields:\n    images:\n        label: Images\n        mode: image\n        useCaption: true\n        thumbOptions:\n            mode: crop\n            extension: auto\n        span: full\n        type: fileupload\n        # Enable the focus point selector\n        focuspoint: true\n```\n\n![focuspoint-configform](https://user-images.githubusercontent.com/10140882/51920398-97a27480-23e5-11e9-91ee-612da085fdb3.JPG)\n\n#### Frontend\n\nYou can use the new `focus` method on any `File` model to get the source to a focus point image.\n\nThe `focus` method has the exact same API as the `thumb` method, you can specify a `height`, `width` and a `mode`.\n\n```twig\n\u003cimg src=\"{{ image.focus(200, 300, 'auto') }}\" alt=\"\"\u003e\n```\n\nThis call will result in the following HTML:\n\n\n```html\n\u003cimg src=\"/storage/temp/public/a9f/2bd/159/offline-focus_30_400_500_50_50_0_0_auto__400.jpg\"\n     alt=\"\"\n     class=\"focuspoint-image\"\n     style=\"width: 100%; height: 100%; object-fit: cover; object-position: 30% 80%;\"\u003e\n```\n\nYou can disable the injection of the inline styles via the plugin's backend settings.\n\nIf you want to use any of the existing focus point JS libraries you can also define a custom container\nthat will be place around the image. The focus coordinates can be injected as custom `data-*` attributes.\n\nAll of these settings are available on the plugin's backend settings page.\n\n```html\n\u003cdiv class=\"focuspoint-container\" data-focus-x=\"50\" data-focus-y=\"30\"\u003e\n    \u003cimg src=\"/storage/temp/public/a9f/2bd/159/offline-focus_30_400_500_50_50_0_0_auto__400.jpg\"\n         alt=\"\"\n         class=\"focuspoint-image\"\n         data-focus-x=\"50\"\n         data-focus-y=\"30\"\n     \u003e\n \u003c/div\u003e\n```\n\n### Browser-Compatibility\n\nBe aware that `object-fit` is not supported in IE without\n[using a polyfill](https://github.com/bfred-it/object-fit-images).\n\n\n## Inlining SVG images\n\nThis plugin registers a simple `svg` helper function that enables you to inline SVG images from your project.\n\n```twig\n\u003c!-- search in theme directory --\u003e\n\u003cdiv class=\"inline-svg-wrapper\"\u003e\n\t{{ svg('assets/icon.svg') }}\n\u003c/div\u003e\n\n\u003c!-- start with a / to search relative to the project's root --\u003e\n\u003cdiv class=\"inline-svg-wrapper\"\u003e\n\t{{ svg('/plugins/vendor/plugin/assets/icon.svg') }}\n\u003c/div\u003e\n```\n\n### Using variables\n\nAside from inlining the SVG itself the helper function will also pass any variables\nalong to the SVG and parse it using October's Twig parser. This means you can\neasily create dynamic SVGs.\n\n```svg\n\u003c!-- icon.svg --\u003e\n\u003csvg fill=\"{{ fill }}\" width=\"{{ width | default(800) }}\"\u003e ...\n```\n\n```html\n\u003c!-- You can pass variables along as a second parameter --\u003e\n\u003cimg src=\"{{ svg('/plugins/xy/assets/icon.svg', {fill: '#f00', width: '200'}) }}\"\u003e\n```\n\n## Bug reports\n\nIt is very likely that there will be bugs with some specific html markup. If you encounter such a bug, please report it.\n\n## Future plans\n\n* Exclude/Include-Filters\n* Maybe a component to enable the middleware only on some pages\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffline-gmbh%2Foc-responsive-images-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foffline-gmbh%2Foc-responsive-images-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffline-gmbh%2Foc-responsive-images-plugin/lists"}