From f0c99d7633cb2baa0ba2a75b2b751f619c5e29b5 Mon Sep 17 00:00:00 2001 From: Simon Hamp Date: Sat, 13 Jan 2024 04:38:19 +0000 Subject: [PATCH] Update readme --- README.md | 131 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 99 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index d75e4e6..537f6c3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![](https://github.com/simonhamp/the-og/blob/main/thumbnail.png?raw=true) -

+

Build Status Latest Stable Version Total Downloads @@ -13,7 +13,7 @@ An OpenGraph image generator written purely in PHP, so you don't need to install or a whole browser instance just to create a dynamic PNG. ## Sponsorship -The OG is completely free to use for personal or commercial use. If it's making your job easier or you just want to +The OG is completely free to use for personal or commercial use. If it's making your job easier, or you just want to make sure it keeps being supported and improved, I'd really appreciate your donations! [Donate now via GitHub Sponsors](https://github.com/sponsors/simonhamp) @@ -57,10 +57,45 @@ And here's the image that generates: The [`Image` class](https://github.com/simonhamp/the-og/blob/main/src/Image.php) provides an elegant and fluent API for configuring the content, style and layout of your image, as well as helpers to render the image and save it to a file. +### Storing images + +Conveniently, you can use the `save()` method to store your image on the local filesystem: + +```php +$image = new Image; +$image->save('/path/to/your/image.png'); +``` + +If you prefer to store your image somewhere other than the local filesystem (e.g. storing it on Amazon S3) you can use +the `toString()` method. + +`toString()` will return the rendered image as a binary string: + +```php +$image = (new Image())->toString(); + +// $service here could be an AWS\S3\S3Client, for example +$service->putObject([ + 'Key' => 'example-image.png', + 'Body' => $image, + 'ContentType' => 'image/png', +]); +``` + +This will send the raw binary data directly to the external service without needing to write the image to a file on the +local disk first. + ### Colors Throughout The OG, colors can be expressed as hex codes, rgba, or HTML named colors. +### Backgrounds + +The OG comes with a number of built-in background patterns that you can use to add some texture to your image. You can +find all of these defined in the [`Background` enum](https://github.com/simonhamp/the-og/blob/main/src/Background.php). + +It also supports custom background images from local or remote sources. + ### Borders Borders provide a subtle variation of color and texture to your image by framing one, or multiple edges of the image @@ -219,12 +254,15 @@ $image->backgroundColor('seagreen') ### Layouts -While themes govern the colors and styles used within your images, layouts govern size of your images and the size and -position of the image's elements (text blocks, other images etc), called **Features**. +While themes govern the _colors_ and _styles_ used within your images, layouts govern size of your images and the +_size_ and _position_ of the image's elements (text blocks, other images etc.), called **Features**. + +Different layouts provide different features. -There are currently 2 layouts: -[`Standard`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/Standard.php) -and [`GitHubBasic`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/GitHubBasic.php). +There are currently 3 layouts: +- [`Standard`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/Standard.php) +- [`GitHubBasic`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/GitHubBasic.php) +- [`TwoUp`](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/TwoUp.php) The default layout is `Standard`. @@ -232,47 +270,76 @@ More layouts are coming. #### Creating layouts -Layout classes are usually a simple class with some basic settings values. +Layouts are simple classes with some basic settings and `features()` method to define all of your image's features. -[Take a look at the Standard layout](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/Standard.php) as -an example. +Each layout class must implement the +[`Layout` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Layout.php) -In it you'll see the basic settings for the layout, such as the dimensions of the canvas, the border size and location, +[Take a look at the Standard layout](https://github.com/simonhamp/the-og/blob/main/src/Layout/Layouts/Standard.php), +or any of the other built-in layouts, as an example. + +In it, you'll see the basic settings for the layout, such as the dimensions of the canvas, the border size and location, and any padding. **All sizes are in pixels.** -Each layout class must implement the -[`Layout` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Layout.php) +#### Features -#### Creating features +Features are the individual elements that make up your image, such as the Title, Description, URL etc. -Features are the individual elements that make up your image, such as the Title, Description, URL, Border, Background -and more. +**All layouts** support a background (which is always rendered first) and a border (which is always rendered last), so +you do not normally need to define these as distinct features. -Different layouts will provide different features, so not all features will be available. At a minimum, a layout should -provide a Title feature so that at least one block of text can be rendered on the image. +Beyond that, the features of the image are entirely defined by the Layout. The order in which they are defined +determines their rendering order and, therefore, their layering. -### Storing the image elsewhere +Available built-in features: +- [`TextBox`](https://github.com/simonhamp/the-og/blob/main/src/Layout/TextBox.php) + Allows you to render a constrained block of text. The size of the box serves to constrain the text; the final size of + the box is determined by the length, font, size, and line height of the rendered text. +- [`PictureBox`](https://github.com/simonhamp/the-og/blob/main/src/Layout/PictureBox.php) + Allows you to render an image. -If you prefer to store your image somewhere other than the local filesystem (e.g. storing it on Amazon S3) you can use -the `toString()` method. +[See the built-in layouts](https://github.com/simonhamp/the-og/tree/main/src/Layout/Layouts) for examples of how to use +these features and add them to a layout. -`toString()` will return the rendered image as a binary string: +#### Positioning features + +Features can be positioned absolutely anywhere on the canvas or relatively to another feature on the canvas. + +To use relative positioning, it's helpful to give your target feature a unique name, which is used when other features +need to reference its final rendered position. + +[See the built-in layouts](https://github.com/simonhamp/the-og/tree/main/src/Layout/Layouts) for examples of how to +position features. + +#### Creating features + +All features must implement the +[`Box` interface](https://github.com/simonhamp/the-og/blob/main/src/Interfaces/Box.php). + +The key method of any feature is the `render()` method, which is responsible for rendering the feature onto the image. +This method receives an instance of the underlying +[`Intervention\Image\Image` class](https://github.com/Intervention/image/blob/develop/src/Image.php), allowing you to +use Intervention's own modifiers directly, e.g.: ```php -$image = (new Image())->toString(); +use Intervention\Image\Interfaces\ImageInterface; -// $service here could be an AWS\S3\S3Client, for example -$service->putObject([ - 'Key' => 'example-image.png', - 'Body' => $image, - 'ContentType' => 'image/png', -]); +public function render(ImageInterface $image) +{ + $image->drawCircle(10, 10, function ($circle) { + $circle->radius(150); + $circle->background('lightblue'); + $circle->border('b53717', 1); + }); +} ``` -This will send the raw binary data directly to the external service without needing to write the image to a file on the -local disk first. +You should, however, extend the [`Box` class](https://github.com/simonhamp/the-og/blob/main/src/Layout/Box.php) as this +provides a number of useful conveniences, especially if you want to use relative positioning. + +```php ## Testing @@ -284,7 +351,7 @@ To run the integration tests, you need to install all Composer dependencies: composer install ``` -You will also need [NodeJS](https://nodejs.org/en) (version 20 or above) and to install the NPM dependencies: +You will also need [Node.js](https://nodejs.org/en) (version 20 or above) and to install the NPM dependencies: ```shell npm install