diff --git a/docs/3-packages/03-responsive-image.md b/docs/3-packages/03-responsive-image.md new file mode 100644 index 000000000..b43a5a4cb --- /dev/null +++ b/docs/3-packages/03-responsive-image.md @@ -0,0 +1,111 @@ +--- +title: Responsive images +description: "A standalone package to render responsive images" +--- + + +## Quickstart + +``` +composer require tempest/responsive-image +``` + +```php +use Tempest\ResponsiveImage\ResponsiveImageFactory; +use Tempest\ResponsiveImage\ResponsiveImageConfig; + +$config = new ResponsiveImageConfig( + srcPath: __DIR__ . '/path/to/image/sources', + publicPath: __DIR__ . '/../public', +); + +$imageFactory = new ResponsiveImageFactory($config); + +$image = $imageFactory->create('/parrot.jpg'); + +echo $image->html; +``` + +```html + +``` + +## In depth + +The goal of this package is to render [responsive images for better web performance](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images). You provide it with a single image source, and this package will generate several responsive downscaled versions of that image. It will then move all images to the correct place and render the image HTML for you. Optionally, you can use [tempest/command-bus](/docs/features/command-bus) to generate responsive images in the background. + +### Basic setup + +Responsive images are generated with the `Tempest\ResponsiveImage\ResponsiveImageFactory` class. It takes one argument: a `Tempest\ResponsiveImage\ResponsiveImageConfig` object. This object looks like this: + +```php +use Tempest\ResponsiveImage\ResponsiveImageConfig; +use Intervention\Image\Drivers\Gd\Driver; +use Intervention\Image\ImageManager; + +$config = new ResponsiveImageConfig( + srcPath: __DIR__ . '/../resources/src/', + publicPath: __DIR__ . '/../public/', + async: true, + cache: true, + imageManager: new ImageManager(new Driver()), +); +``` +| Parameter | Description | +|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `{:hl-property:srcPath:}` | The path to the directory where all source images are stored. | +| `{:hl-property:publicPath:}` | The path to the public directory where rendered images should be served from. | +| `{:hl-property:async:}` | Whether responsive images should be generated in the background. This paramater is only taken into account if Tempest's command bus is installed. | +| `{:hl-property:cache:}` | Whether generated responsive variants should be cached. If true, then responsive variants won't be generated as long as the main image file exists in the public path. Cache clearing should be done manually on your end. | +| `{:hl-property:imageManager:}` | The Intervention imagemanager. Refer to the [Intervention docs](https://image.intervention.io/v4) for all options. | + +### Image rendering + +With a `ResponsiveImageFactory` in place, you can now render images. The only thing you need to do is pass it the image source (like it would be used in the HTML tag), and the factory will handle the rest. The final result will be an `Image` object that can be rendered to HTML. + +```php +$imageFactory = new ResponsiveImageFactory($config); + +$image = $imageFactory->create('/parrot.jpg'); +// This image `/parrot.jpg` is assumed to be present in the defined `srcPath`. +// It will be copied, together with its responsive variants to `publicPath` + +echo $image->html; + +// +``` + +### Image rendering options + +The factory will fill in and generate the image's `{:hl-property:srcset:}` for you based on image file sizes. However, you can also pass additional attributes to be added to the image's HTML: + +```php +$image = $factory->create( + src: '/parrot.jpg', + alt: 'A parrot', + sizes: [new Size(maxWidth: 1000, width: 300), new Size(maxWidth: 1500, width: 500)], + lazy: true, +); +``` + +```html +A parrot +``` + +## Integrations + +### Async image processing + +You can combine this package with [tempest/command-bus](/docs/features/command-bus) to enable async image processing. This will make it so that the responsive variations of an image are rendered in the background. The main image will still be copied immediately, so you won't have to wait until processing is done. + +Read about how to install Tempest's command bus as a standalone component [here](/docs/extra-topics/standalone-components#tempest-command-bus). + +### Markdown parsing + +This package is used by [`tempest/markdown`](/docs/packages/markdown) to render responsive images from markdown files. \ No newline at end of file diff --git a/docs/3-packages/04-markdown.md b/docs/3-packages/04-markdown.md new file mode 100644 index 000000000..66e2d6807 --- /dev/null +++ b/docs/3-packages/04-markdown.md @@ -0,0 +1,97 @@ +--- +title: Markdown +description: "Fast and extensible Markdown in PHP" +--- + +`tempest/markdown` is a Markdown parser written in PHP. It's designed to be fast and extensible and has a bunch of additional features built-in like code highlighting, responsive images, tables, and frontmatter support. + +## Quickstart + +```sh +composer require tempest/markdown +``` + +Render Markdown like this: + +```php +use Tempest\Markdown\Markdown; + +$markdown = new Markdown(); + +$parsed = $markdown->parse(file_get_contents('README.md')); + +echo $parsed->frontMatter['title']; +echo $parsed->html; +``` + +## Integrations + +### Code highlighting + +`tempest/markdown` comes with code highlighting out of the box powered by [`tempest/highlight`](/docs/packages/highlight). You can configure the highlighter by passing a new instance into the markdown parser: + +```php +use Tempest\Markdown\Markdown; +use Tempest\Highlight\Highlighter; + +$markdown = new Markdown( + highlighter: new Highlighter( + // Configure theme, etc + ), +); +``` + +Language definitions work in both inline and pre code blocks: + +
+This is an inline PHP codeblock: `{php}echo "Hello";`
+
+ +
+This is a pre PHP codeblock:
+
+```php
+echo "world";
+```
+
+ +You can disable all code highlighting by passing in `{php}null`: + +```php +$markdown = new Markdown( + highlighter: null, +); +``` + +### Responsive images + +`tempest/markdown` has support for responsive images powered by [`tempest/responsive-image`](/docs/packages/responsive-image). You'll need to configure the responsive image factory before being able to use it. + +```php +use Tempest\Markdown\Markdown; +use Tempest\ResponsiveImage\ResponsiveImageConfig; +use Tempest\ResponsiveImage\ResponsiveImageFactory; + +$imageConfig = new ResponsiveImageConfig( + srcPath: __DIR__ . '/../resources/images', + publicPath: __DIR__ . '/../public', +); + +$markdown = new Markdown( + imageFactory: new ResponsiveImageFactory($imageConfig), +); +``` + +## Performance + +This package began as a challenge to make a more performant Markdown parser in pure PHP. The primary performance gain is from not relying on regex but instead using a simple lexer to tokenize Markdown files and convert them to HTML. + +Benchmarks are included in this repo and can be run with `composer bench` after installing all dev dependencies. Here are the results on a local machine rendering the full Tempest docs: + +| Package | Memory | Time to parse | +|------------------------|----------|---------------| +| tempest/markdown | 5.944mb | 6.281ms | +| league/commonmark | 21.114mb | 56.993ms | +| michelf/php-markdown | 7.343mb | 23.215ms | +| erusev/parsedown-extra | 8.485mb | 15.163ms | +