From 2f685b38a11c18c57247636c55162d50157bd28d Mon Sep 17 00:00:00 2001 From: Oh My Felix Date: Tue, 23 Jun 2026 06:40:32 +0000 Subject: [PATCH] Docs: move documentation to README. Co-authored-by: Felix --- .docs/README.md | 252 ---------------------------------------------- README.md | 261 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 253 insertions(+), 260 deletions(-) delete mode 100644 .docs/README.md diff --git a/.docs/README.md b/.docs/README.md deleted file mode 100644 index 72ee592..0000000 --- a/.docs/README.md +++ /dev/null @@ -1,252 +0,0 @@ -# Contributte Application - -## Content - -- [Setup](#setup) -- [UI](#ui) - - [Presenter](#presenter) - - [StructuredTemplates](#structured-templates) - - [Control](#control) - - [Component](#component) -- [Responses](#responses) - - [CSVResponse](#csvresponse) - - [ImageResponse](#imageresponse) - - [JsonPrettyResponse](#psr7streamresponse) - - [PSR7StreamResponse](#flyresponse) - - [FlyResponse - send file/buffer on-the-fly](#flyresponse) - - [XmlResponse](#xmlresponse) - - [StringResponse](#stringresponse) - -## Setup - -```bash -composer require contributte/application -``` - -## UI - -### Presenter - -By extending the `BasePresenter` you can use these methods: - -| Methods | Return | Description | -|---------|--------|-------------| -| `isModuleCurrent($module)` | `boolean` | Is the current presenter in a given module? | -| `getModuleName()` | `string` | Get current presenter's module name. | - -#### Structured Templates - -A trait which modifies where the presenter templates are loaded from. - -- Views - - `%presenterDir%/templates/%view%.latte` -- Layouts - - `%presenterDir%/templates/@layout.latte` - - layouts of parent presenters are also looked for - -```php -use Contributte\Application\UI\Presenter\StructuredTemplates; -use Nette\Application\UI\Presenter; - -class YourPresenter extends Presenter -{ - use StructuredTemplates; -} -``` - -### Control - -- NullControl - displays nothing - -### Component - -- NullComponent - displays nothing - -## Responses - -- CSVResponse -- ImageResponse -- JsonPrettyResponse -- PSR7StreamResponse -- FlyResponse -- XmlResponse -- StringResponse - -### CSVResponse - -```php -$presenter->sendResponse(new CSVResponse($data)); - -# Define own filename -$presenter->sendResponse(new CSVResponse($data, 'export-2018.csv'); - -# Set delimiter and include BOM -$presenter->sendResponse(new CSVResponse($data, 'export.csv', 'utf-8', '|', TRUE)); -``` -### ImageResponse - -```php -$presenter->sendResponse(new ImageResponse($image)); - -# String filepath -$presenter->sendResponse(new ImageResponse('/path/to/file.png')); -``` - -### JsonPrettyResponse - -```php -$presenter->sendResponse(new JsonPrettyResponse($json, 'application/json)); -``` - -### PSR7StreamResponse - -```php -$presenter->sendResponse(new PSR7StreamResponse($stream, 'invoice.pdf', 'application/octet-stream')); -``` - -### FlyResponse - -There are 2 types of fly response: - -- **FlyResponse** - General purpose fly response. -- **FlyFileResponse** - Special response for handling files on-the-fly. - -### XmlResponse - -```php -$presenter->sendResponse(new XmlResponse($xml)); -``` -### StringResponse - -```php -$response = new StringResponse($pdfString, 'invoice.pdf', 'application/pdf'); -$response->setAttachment(); // browser download the file - -$presenter->sendResponse($response); -``` - -### Adapters - -#### ProcessAdapter - -Execute a command over [popen](http://php.net/manual/en/function.popen.php). - -```php -use Contributte\Application\Response\Fly\Adapter\ProcessAdapter; -use Contributte\Application\Response\Fly\FlyFileResponse; - -// Compress the current folder and send it to a response -$adapter = new ProcessAdapter('tar cf - ./ | gzip -c -f'); -$response = new FlyFileResponse($adapter, 'folder.tgz'); - -$this->sendResponse($response); -``` - -#### StdoutAdapter - -Write to `php://output`. - -```php -use Contributte\Application\Response\Fly\Adapter\StdoutAdapter; -use Contributte\Application\Response\Fly\Buffer\Buffer; -use Contributte\Application\Response\Fly\FlyFileResponse; -use Nette\Http\IRequest; -use Nette\Http\IResponse; - -// Write to stdout over buffer class -$adapter = new StdoutAdapter(function(Buffer $buffer, IRequest $request, IResponse $response) { - // Modify headers - $response->setHeader(..); - - // Write data - $buffer->write('Some data..'); -}); -$response = new FlyFileResponse($adapter, 'my.data'); - -$this->sendResponse($response); -``` - -#### CallbackAdapter - -```php -use Contributte\Application\Response\Fly\Adapter\CallbackAdapter; -use Contributte\Application\Response\Fly\FlyFileResponse; -use Nette\Http\IRequest; -use Nette\Http\IResponse; - -$adapter = new CallbackAdapter(function(IRequest $request, IResponse $response) use ($model) { - // Modify headers - $response->setHeader(..); - - // Fetch topsecret data - $data = $this->facade->getData(); - foreach ($data as $d) { - // Write or print data.. - } -}); -$response = new FlyFileResponse($adapter, 'my.data'); - -$this->sendResponse($response); -``` - -### Model - -```php -final class BigOperationHandler -{ - - /** @var Facade */ - private $facade; - - /** - * @param Facade $facade - */ - public function __construct(Facade $facade) - { - $this->facade = $facade; - } - - public function toFlyResponse() - { - $adapter = new CallbackAdapter(function (IRequest $request, IResponse $response) { - // Modify headers - $response->setHeader(..); - - // Fetch topsecret data - $data = $this->facade->getData(); - foreach ($data as $d) { - // Write or print data.. - } - }); - - return new FlyFileResponse($adapter, 'file.ext'); - - // or - return new FlyResponse($adapter); - } -} - -interface IBigOperationHandlerFactory -{ - - /** - * @return BigOperationHandler - */ - public function create(); - -} - -final class MyPresenter extends Nette\Application\UI\Presenter -{ - - /** @var IBigOperationHandlerFactory @inject */ - public $bigOperationHandlerFactory; - - public function handleMagic() - { - $this->sendResponse( - $this->bigOperationHandlerFactory->create()->toFlyResponse() - ); - } -} -``` diff --git a/README.md b/README.md index 6df5e52..f34720f 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,16 @@ Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

-## Usage +Small extensions for Nette Application, including base UI helpers, null components, structured templates, and response implementations. + +## Versions + +| State | Version | Branch | Nette | PHP | +|-------------|---------|----------|-------|---------| +| dev | `^0.7` | `master` | 3.2+ | `>=8.2` | +| stable | `^0.6` | `master` | 3.0+ | `>=8.1` | + +## Installation To install latest version of `contributte/application` use [Composer](https://getcomposer.org). @@ -26,17 +35,253 @@ To install latest version of `contributte/application` use [Composer](https://ge composer require contributte/application ``` -## Documentation +## Content -For details on how to use this package, check out our [documentation](.docs). +- [UI](#ui) + - [Presenter](#presenter) + - [Structured Templates](#structured-templates) + - [Control](#control) + - [Component](#component) +- [Responses](#responses) + - [CSVResponse](#csvresponse) + - [ImageResponse](#imageresponse) + - [JsonPrettyResponse](#jsonprettyresponse) + - [PSR7StreamResponse](#psr7streamresponse) + - [FlyResponse](#flyresponse) + - [XmlResponse](#xmlresponse) + - [StringResponse](#stringresponse) + - [Adapters](#adapters) + - [Model](#model) -## Versions +## UI -| State | Version | Branch | Nette | PHP | -|-------------|---------|----------|-------|---------| -| dev | `^0.7` | `master` | 3.2+ | `>=8.2` | -| stable | `^0.6` | `master` | 3.0+ | `>=8.1` | +### Presenter + +By extending the `BasePresenter` you can use these methods: + +| Methods | Return | Description | +|---------|--------|-------------| +| `isModuleCurrent($module)` | `boolean` | Is the current presenter in a given module? | +| `getModuleName()` | `string` | Get current presenter's module name. | + +#### Structured Templates + +A trait which modifies where the presenter templates are loaded from. + +- Views + - `%presenterDir%/templates/%view%.latte` +- Layouts + - `%presenterDir%/templates/@layout.latte` + - layouts of parent presenters are also looked for + +```php +use Contributte\Application\UI\Presenter\StructuredTemplates; +use Nette\Application\UI\Presenter; + +class YourPresenter extends Presenter +{ + use StructuredTemplates; +} +``` + +### Control + +- NullControl - displays nothing + +### Component + +- NullComponent - displays nothing + +## Responses + +- CSVResponse +- ImageResponse +- JsonPrettyResponse +- PSR7StreamResponse +- FlyResponse +- XmlResponse +- StringResponse + +### CSVResponse + +```php +$presenter->sendResponse(new CSVResponse($data)); + +// Define own filename +$presenter->sendResponse(new CSVResponse($data, 'export-2018.csv')); + +// Set delimiter and include BOM +$presenter->sendResponse(new CSVResponse($data, 'export.csv', 'utf-8', '|', true)); +``` + +### ImageResponse + +```php +$presenter->sendResponse(new ImageResponse($image)); + +// String filepath +$presenter->sendResponse(new ImageResponse('/path/to/file.png')); +``` + +### JsonPrettyResponse + +```php +$presenter->sendResponse(new JsonPrettyResponse($json, 'application/json')); +``` + +### PSR7StreamResponse + +```php +$presenter->sendResponse(new PSR7StreamResponse($stream, 'invoice.pdf', 'application/octet-stream')); +``` + +### FlyResponse +There are 2 types of fly response: + +- **FlyResponse** - General purpose fly response. +- **FlyFileResponse** - Special response for handling files on-the-fly. + +### XmlResponse + +```php +$presenter->sendResponse(new XmlResponse($xml)); +``` + +### StringResponse + +```php +$response = new StringResponse($pdfString, 'invoice.pdf', 'application/pdf'); +$response->setAttachment(); // browser download the file + +$presenter->sendResponse($response); +``` + +### Adapters + +#### ProcessAdapter + +Execute a command over [popen](https://www.php.net/manual/en/function.popen.php). + +```php +use Contributte\Application\Response\Fly\Adapter\ProcessAdapter; +use Contributte\Application\Response\Fly\FlyFileResponse; + +// Compress the current folder and send it to a response +$adapter = new ProcessAdapter('tar cf - ./ | gzip -c -f'); +$response = new FlyFileResponse($adapter, 'folder.tgz'); + +$this->sendResponse($response); +``` + +#### StdoutAdapter + +Write to `php://output`. + +```php +use Contributte\Application\Response\Fly\Adapter\StdoutAdapter; +use Contributte\Application\Response\Fly\Buffer\Buffer; +use Contributte\Application\Response\Fly\FlyFileResponse; +use Nette\Http\IRequest; +use Nette\Http\IResponse; + +// Write to stdout over buffer class +$adapter = new StdoutAdapter(function(Buffer $buffer, IRequest $request, IResponse $response) { + // Modify headers + $response->setHeader(..); + + // Write data + $buffer->write('Some data..'); +}); +$response = new FlyFileResponse($adapter, 'my.data'); + +$this->sendResponse($response); +``` + +#### CallbackAdapter + +```php +use Contributte\Application\Response\Fly\Adapter\CallbackAdapter; +use Contributte\Application\Response\Fly\FlyFileResponse; +use Nette\Http\IRequest; +use Nette\Http\IResponse; + +$adapter = new CallbackAdapter(function(IRequest $request, IResponse $response) use ($model) { + // Modify headers + $response->setHeader(..); + + // Fetch topsecret data + $data = $this->facade->getData(); + foreach ($data as $d) { + // Write or print data.. + } +}); +$response = new FlyFileResponse($adapter, 'my.data'); + +$this->sendResponse($response); +``` + +### Model + +```php +final class BigOperationHandler +{ + + /** @var Facade */ + private $facade; + + /** + * @param Facade $facade + */ + public function __construct(Facade $facade) + { + $this->facade = $facade; + } + + public function toFlyResponse() + { + $adapter = new CallbackAdapter(function (IRequest $request, IResponse $response) { + // Modify headers + $response->setHeader(..); + + // Fetch topsecret data + $data = $this->facade->getData(); + foreach ($data as $d) { + // Write or print data.. + } + }); + + return new FlyFileResponse($adapter, 'file.ext'); + + // or + return new FlyResponse($adapter); + } +} + +interface IBigOperationHandlerFactory +{ + + /** + * @return BigOperationHandler + */ + public function create(); + +} + +final class MyPresenter extends Nette\Application\UI\Presenter +{ + + /** @var IBigOperationHandlerFactory @inject */ + public $bigOperationHandlerFactory; + + public function handleMagic() + { + $this->sendResponse( + $this->bigOperationHandlerFactory->create()->toFlyResponse() + ); + } +} +``` ## Development