{"id":13545507,"url":"https://github.com/simonhamp/the-og","last_synced_at":"2025-05-15T11:05:32.871Z","repository":{"id":213726453,"uuid":"734784961","full_name":"simonhamp/the-og","owner":"simonhamp","description":"A pure PHP OpenGraph Image Generator","archived":false,"fork":false,"pushed_at":"2025-03-11T19:20:48.000Z","size":14022,"stargazers_count":271,"open_issues_count":1,"forks_count":15,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-07T18:05:56.369Z","etag":null,"topics":["generator","image-generation","opengraph-images","php"],"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/simonhamp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"simonhamp"}},"created_at":"2023-12-22T15:59:14.000Z","updated_at":"2025-04-06T11:22:00.000Z","dependencies_parsed_at":"2023-12-22T17:22:02.046Z","dependency_job_id":"79749fab-344b-4fdb-80ef-71e843cad40f","html_url":"https://github.com/simonhamp/the-og","commit_stats":null,"previous_names":["simonhamp/the-og"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhamp%2Fthe-og","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhamp%2Fthe-og/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhamp%2Fthe-og/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhamp%2Fthe-og/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonhamp","download_url":"https://codeload.github.com/simonhamp/the-og/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248960751,"owners_count":21189988,"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":["generator","image-generation","opengraph-images","php"],"created_at":"2024-08-01T11:01:04.377Z","updated_at":"2025-04-14T20:46:24.271Z","avatar_url":"https://github.com/simonhamp.png","language":"PHP","funding_links":["https://github.com/sponsors/simonhamp"],"categories":["PHP","Image Generation \u0026 Editing"],"sub_categories":[],"readme":"![](https://github.com/simonhamp/the-og/blob/main/thumbnail.png?raw=true)\n\n\u003cp class=\"text-center\"\u003e\n\u003ca href=\"https://github.com/simonhamp/the-og/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/simonhamp/the-og/run-tests.yml?style=for-the-badge\u0026label=tests\" alt=\"Build Status\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/simonhamp/the-og/releases\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/simonhamp/the-og?style=for-the-badge\u0026label=latest\" alt=\"Latest Stable Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/simonhamp/the-og/stats\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/simonhamp/the-og?style=for-the-badge\u0026label=installs\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/simonhamp/the-og/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/simonhamp/the-og?style=for-the-badge\u0026label=license\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# The OG\n\nAn OpenGraph image generator written purely in PHP, so you don't need to install another runtime somewhere\nor a whole browser instance just to create a dynamic PNG.\n\n## Sponsorship\nThe OG is completely free to use for personal or commercial use. If it's making your job easier, or you just want to\nmake sure it keeps being supported and improved, I'd really appreciate your donations!\n\n[Donate now via GitHub Sponsors](https://github.com/sponsors/simonhamp)\n\nIf you're using The OG, I'd love to see your creations! Please send me a tweet/toot\n([@simonhamp](https://twitter.com/simonhamp),\n[@simonhamp@phpc.social](https://phpc.social/@simonhamp))\nwith some links so I can see how you're using The OG in the wild.\n\nThank you 🙏\n\n## Sponsors\n\n[Laradir](https://laradir.com/?ref=the-og-github) - Connecting the best Laravel Developers with the best Laravel Teams.  \n[quantumweb](https://quantumweb.co/?ref=simonhamp/the-og-github) - A bare-metal web agency. Less layers, better results.  \n[RedGalaxy](https://www.redgalaxy.co.uk) - A web application development studio based in Cambridgeshire, building solutions to help businesses improve efficiency and profitability.  \n[Sevalla](https://sevalla.com/?utm_source=nativephp\u0026utm_medium=Referral\u0026utm_campaign=homepage) - Host and manage your applications, databases, and static sites in a single, intuitive platform.  \n\n## Installation\n\nInstall via Composer:\n\n```shell\ncomposer require simonhamp/the-og\n```\n\n## Usage\n\nUsing The OG is really simple. Here's a basic example:\n\n```php\nuse SimonHamp\\TheOg\\Background;\nuse SimonHamp\\TheOg\\Image;\n\n(new Image())\n    -\u003eaccentColor('#cc0000')\n    -\u003eborder()\n    -\u003eurl('https://example.com/blog/some-blog-post-url')\n    -\u003etitle('Some blog post title that is quite big and quite long')\n    -\u003edescription(\u003c\u003c\u003c'TEXT'\n        Some slightly smaller but potentially much longer subtext. It could be really long so we might need to trim it completely after many words.\n\n        Some slightly smaller but potentially much longer subtext. It could be really long so we might need to trim it completely after many words.\n    TEXT)\n    -\u003ebackground(Background::JustWaves, 0.2)\n    -\u003esave(__DIR__.'/test.png');\n```\n\nAnd here's the image that generates:\n\n![](https://github.com/simonhamp/the-og/blob/main/tests/Integration/__snapshots__/ImageTest__test_basic_image%20with%20data%20set%20override%20some%20elements__1.png)\n\nThe [`Image` class](https://github.com/simonhamp/the-og/blob/main/src/Image.php) provides an elegant and fluent API for\nconfiguring the content, style and layout of your image, as well as helpers to render the image and save it to a file.\n\n### Checking your images\n\nWant to see how your images will look when shared on social media? Check out [SEOToolkit's Social Share preview](https://seotoolkit.dev/social)\n\n### Storing images\n\nConveniently, you can use the `save()` method to store your image on the local filesystem:\n\n```php\n$image = new Image;\n$image-\u003esave('/path/to/your/image.png');\n```\n\nIf you prefer to store your image somewhere other than the local filesystem (e.g. storing it on Amazon S3) you can use\nthe `toString()` method.\n\n`toString()` will return the rendered image as a binary string:\n\n```php\n$image = (new Image())-\u003etoString();\n\n// $service here could be an AWS\\S3\\S3Client, for example\n$service-\u003eputObject([\n    'Key' =\u003e 'example-image.png',\n    'Body' =\u003e $image,\n    'ContentType' =\u003e 'image/png',\n]);\n```\n\nThis will send the raw binary data directly to the external service without needing to write the image to a file on the\nlocal disk first.\n\n#### Image formats\n\nBy default, The OG encodes images in **PNG format**.\n\nIf you wish to use a different format, however, you can! Simply\npass an instance of the relevant\n[`intervention/image` encoder](https://github.com/Intervention/image/tree/develop/src/Encoders)\nto the `save()` or `toString()` methods:\n\n\n```php\nuse Intervention\\Image\\Encoders\\WebpEncoder;\n\n$image-\u003etoString(encoder: new WebpEncoder);\n```\n\n### Colors\n\nThroughout The OG, colors can be expressed as hex codes, rgba, or HTML named colors.\n\n### Backgrounds\n\nThe OG comes with a number of built-in background patterns that you can use to add some texture to your image. You can\nfind all of these defined in the [`Background` enum](https://github.com/simonhamp/the-og/blob/main/src/Background.php).\n\nBackgrounds can be set to `Repeat` or `Cover` and have opacity too:\n\n```php\nuse SimonHamp\\TheOg\\Background;\nuse SimonHamp\\TheOg\\BackgroundPlacement;\n\n(new Image)-\u003ebackground(\n    background: Background::JustWaves,\n    opacity: 0.5,\n    placement: BackgroundPlacement::Cover\n);\n```\n\nIt also supports custom background images from local or remote sources.\nSee the [Custom Background Images](#custom-background-images) section below.\n\n### Borders\n\nBorders provide a subtle variation of color and texture to your image by framing one, or multiple edges of the image\nwith a single band of color—usually the theme's `accentColor`.\n\nBorders are usually defined as part of the theme, but you can override the border position, color and size on the image\nitself:\n\n```php\nuse SimonHamp\\TheOg\\BorderPosition;\n\n$image = new Image;\n$image-\u003eborder(BorderPosition::Top, 'pink', 10);\n```\n\nThe available border positions are:\n\n- `BorderPosition::All` - All 4 edges will be bordered\n- `BorderPosition::Bottom` - The bottom edge will be bordered\n- `BorderPosition::Left` - The left edge will be bordered\n- `BorderPosition::Right` - The right edge will be bordered\n- `BorderPosition::None` - No edges will be bordered\n- `BorderPosition::Top` - The top edge will be bordered\n- `BorderPosition::X` - Combines `BorderPosition::Top` and `BorderPosition::Bottom`\n- `BorderPosition::Y` - Combines `BorderPosition::Left` and `BorderPosition::Right`\n\n\n#### Removing default borders\n\nYou can remove the default border from the image by chaining the `border()` method with the `position` argument set to\n`BorderPosition::None`:\n\n```php\n$image = new Image;\n$image-\u003eborder(BorderPosition::None);\n```\n\n### Themes\n\nThemes set the colors, fonts, and styles for your image. There are currently 2 themes available:\n`Light` and `Dark`.\n\nThe default theme is `Light`.\n\nYou can set the theme on your image at any point before it's rendered:\n\n```php\nuse SimonHamp\\TheOg\\Theme;\n\n$image = new Image;\n$image-\u003etheme(Theme::Dark);\n```\n\n#### Creating themes\n\nThemes are simple classes that implement the\n[`Theme` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Theme.php).\n\nHowever, you can create your own theme most easily by simply instantiating the\n[`Theme` class](https://github.com/simonhamp/the-og/blob/main/src/Theme/Theme.php):\n\n```php\nuse SimonHamp\\TheOg\\Theme\\Fonts\\Inter;\nuse SimonHamp\\TheOg\\Theme\\Theme;\n\n$theme = new Theme(\n    accentColor: '#247BA0',\n    backgroundColor: '#ECEBE4',\n    baseColor: '#153B50',\n    baseFont: Inter::bold(),\n    callToActionBackgroundColor: '#153B50',\n    callToActionColor: '#ECEBE4',\n    descriptionColor: '#429EA6',\n    descriptionFont: Inter::light(),\n    titleFont: Inter::black(),\n);\n\n$image = new Image;\n$image-\u003etheme($theme);\n```\n\n#### Fonts\n\nCurrently, there are 2 fonts available (each with 4 variants):\n- [`Inter`](https://github.com/simonhamp/the-og/blob/main/src/Theme/Fonts/Inter.php)\n- [`RobotoSlab`](https://github.com/simonhamp/the-og/blob/main/src/Theme/Fonts/Inter.php)\n\nIf you think a particular font will make sense added to the core of this package, please consider\n[contributing](#contributing) and open a Pull Request.\n\n#### Custom fonts\n\nYou can load custom fonts by creating a class that implements the\n[`Font` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Font.php):\n\n```php\nuse SimonHamp\\TheOg\\Interfaces\\Font;\n\nclass CustomFont implements Font\n{\n    public function path(): string\n    {\n        return '/path/to/your/font/source/file.ttf';\n    }\n}\n```\n\nThen you can load this font when defining your theme:\n\n```php\n$font = new CustomFont;\n\n$theme = new Theme(\n    baseFont: $font,\n);\n```\n\n#### Custom background images\n\nIf the built-in background patterns don't tickle your fancy, you can load your own simply by instantiating the\n[`Background` class](https://github.com/simonhamp/the-og/blob/main/src/Theme/Background.php):\n\n```php\nuse SimonHamp\\TheOg\\Theme\\Background;\n\n$background = new Background('/path/to/your/image.png');\n```\n\nThen you can pass the background to your custom theme, or directly to your image:\n\n```php\n$theme = new Theme(\n    background: $background,\n);\n\n$image = (new Image)-\u003etheme($theme);\n\n// Or\n\n$image-\u003ebackground($background);\n```\n\nIf you want more customization of the background, you may create your own background classes that implement the\n[`Background` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Background.php).\n\n#### Overriding theme settings\n\nYou can override some theme settings, such as the accent color, background and background color, without having to\ncreate a whole new theme.\n\n```php\n$image = new Image;\n$image-\u003ebackgroundColor('seagreen')\n    -\u003ebackground($customBackground);\n```\n\n### Layouts\n\nWhile themes govern the _colors_ and _styles_ used within your images, layouts govern the _size of your images_ and the\n_size_ and _position_ of the image's elements (text blocks, other images etc.), called **features**.\n\nDifferent layouts provide different features.\n\nThere are currently 3 layouts:\n- [`Standard`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/Standard.php)\n- [`GitHubBasic`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/GitHubBasic.php)\n- [`TwoUp`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/TwoUp.php)\n\nThe default layout is `Standard`.\n\nMore layouts are coming.\n\n#### Creating layouts\n\nLayouts are simple classes with some basic settings and `features()` method to define all of your image's features.\n\nEach layout class must implement the\n[`Layout` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Layout.php)\n\n[Take a look at the Standard layout](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/Standard.php),\nor any of the other built-in layouts, as an example.\n\nIn it, you'll see the basic settings for the layout, such as the dimensions of the canvas, the border size and location,\nand any padding.\n\n**All sizes are in pixels.**\n\n#### Features\n\nFeatures are the individual elements that make up your image, such as the Title, Description, URL etc.\n\n**All layouts** support a background (which is always rendered first) and a border (which is always rendered last), so\nyou do not normally need to define these as distinct features.\n\nBeyond that, the features of the image are entirely defined by the Layout. The order in which they are defined\ndetermines their rendering order and, therefore, their layering.\n\nAvailable built-in features:\n- [`TextBox`](https://github.com/simonhamp/the-og/blob/main/src/Layout/TextBox.php)\n  Allows you to render a constrained block of text. The size of the box serves to constrain the text; the final size of\n  the box is determined by the length, font, size, and line height of the rendered text.\n- [`PictureBox`](https://github.com/simonhamp/the-og/blob/main/src/Layout/PictureBox.php)\n  Allows you to render an image.\n\n[See the built-in layouts](https://github.com/simonhamp/the-og/tree/main/src/Layout/Layouts) for examples of how to use\nthese features and add them to a layout.\n\n#### Positioning features\n\nFeatures can be positioned absolutely anywhere on the canvas or relatively to another feature on the canvas.\n\nTo use relative positioning, it's helpful to give your target feature a unique name, which is used when other features\nneed to reference its final rendered position.\n\n[See the built-in layouts](https://github.com/simonhamp/the-og/tree/main/src/Layout/Layouts) for examples of how to\nposition features.\n\n#### Creating features\n\nAll features must implement the\n[`Box` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Box.php).\n\nThe key method of any feature is the `render()` method, which is responsible for rendering the feature onto the image.\nThis method receives an instance of the underlying\n[`Intervention\\Image\\Image` class](https://github.com/Intervention/image/blob/develop/src/Image.php), allowing you to\nuse Intervention's own modifiers directly, e.g.:\n\n```php\nuse Intervention\\Image\\Interfaces\\ImageInterface;\n\npublic function render(ImageInterface $image)\n{\n  $image-\u003edrawCircle(10, 10, function ($circle) {\n      $circle-\u003eradius(150);\n      $circle-\u003ebackground('lightblue');\n      $circle-\u003eborder('b53717', 1);\n  });\n}\n```\n\nYou should, however, extend the [`Box` class](https://github.com/simonhamp/the-og/blob/main/src/Layout/Box.php) as this\nprovides a number of useful conveniences, especially if you want to use relative positioning.\n\n## Testing\n\nThe OG uses PHPUnit with [snapshot testing](https://github.com/spatie/phpunit-snapshot-assertions).\n\nTo run the integration tests, you need to install all Composer dependencies:\n\n```shell\ncomposer install\n```\n\nYou will also need [Node.js](https://nodejs.org/en) (version 20 or above) and to install the NPM dependencies:\n\n```shell\nnpm install\n```\n\nOnce done, you can execute the tests:\n\n```shell\n./vendor/bin/phpunit\n```\n\n## Contributing\n\nI'd really appreciate and welcome any PRs to help improve this package!\n\n\u003c!-- Please see [CONTRIBUTING](CONTRIBUTING.md) for details. --\u003e\n\n## Support\n\nAll support is handled via [GitHub Issues](https://github.com/simonhamp/the-og/issues).\n\n## License\n\nThe MIT License (MIT). Please see [LICENSE](LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonhamp%2Fthe-og","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonhamp%2Fthe-og","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonhamp%2Fthe-og/lists"}