Skip to content

Commit 7bc632e

Browse files
ericgesericges
committed
update README.md
1 parent 62a3158 commit 7bc632e

File tree

1 file changed

+88
-70
lines changed

1 file changed

+88
-70
lines changed

‎README.md

Lines changed: 88 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -7,58 +7,77 @@
77

88
This bundle offers various utility functionality for the Contao CMS.
99

10-
11-
## Install
10+
> [!NOTE]
11+
> We are currently maintaining two branches of this bundle.
12+
>
13+
> - The `v3` branch is the current stable version.
14+
> - The `v2` branch is this legacy version.
15+
>
16+
> The `v3` branch is a major rewrite of the bundle and has maintained little backwards compatibility with the `v2` branch.
17+
> To aid in migrating to the new version, we are backporting reasonable features from `v3` to `v2`.
18+
>
19+
> We are providing bugfixes and security updates for the `v2` branch for the time being.
20+
21+
## Install
1222

1323
1. Install via composer:
1424
```
15-
composer require heimrichhannot/contao-utils-bundle
25+
composer require heimrichhannot/contao-utils-bundle:^2.0
1626
```
17-
1. Update database
27+
2. Update database
1828
19-
### Additional Requirements:
29+
### Optional Requirements
2030
2131
Add following dependencies to your project composer file, if you want to use one of the following utils:
2232
23-
Util | Dependency
24-
----------------------|-----------
25-
[~~PdfCreator - mPDF~~](docs/utils/pdf/pdfcreator.md) | `"mpdf/mpdf": "^7.0\|^8.0"`
26-
huh.utils.pdf.preview | `"spatie/pdf-to-image": "^1.8"` or/and `"alchemy/ghostscript": "^4.1"`
27-
33+
| Util | Dependency |
34+
|-------------------------------------------------------|------------------------------------------------------------------------|
35+
| [~~PdfCreator - mPDF~~](docs/utils/pdf/pdfcreator.md) | `"mpdf/mpdf": "^7.0\|^8.0"` |
36+
| huh.utils.pdf.preview | `"spatie/pdf-to-image": "^1.8"` or/and `"alchemy/ghostscript": "^4.1"` |
2837
2938
## Usage
3039
31-
### Utils
40+
### Service Locator
3241
33-
> We're currently in a process moving all services into the Utils namespace and make them all accessible from a new Utils service.
42+
This is a backport and essential feature of the `v3` branch. We recommend to refactor your code to use the `Utils`-service locator, and to only use this pattern in new code.
3443
35-
This Bundle is a collection of utils to solve recurring tasks. See the [API Documentation](https://heimrichhannot.github.io/contao-utils-bundle/) to see all util-classes and -methods.
44+
> [!NOTE]
45+
> We're currently in a process to move all services into the Utils namespace and make them all accessible from the new Utils service.
3646
37-
The default way to access the util methods is the `Utils`-service (currently not all services are available there yet). The utils service is best used with dependency injection, but is also available from the service container as public service for usage in legacy code.
47+
This Bundle is a collection of utils to solve recurring tasks. See the [API Documentation](https://heimrichhannot.github.io/contao-utils-bundle/) for all util classes and methods.
3848
39-
```php
40-
use HeimrichHannot\UtilsBundle\Util\Utils;
41-
42-
class MyClass{
43-
/** @var Utils */
44-
protected $utils;
45-
46-
public function __construct(Utils $utils) {
47-
$this->utils = $utils;
48-
}
49-
50-
public function someActions(): bool {
51-
return $this->utils->string()->startsWith('Lorem ipsum dolor sit amet', 'Lorem');
52-
}
53-
}
54-
```
49+
The "default" way to access utils is the `Utils`-service
50+
51+
> [!NOTE]
52+
> Currently, not all services have been backported to the new service locator and are still only available through service tags.
53+
54+
The utils service is used best with dependency injection, but is also available from the service container as a public service to be used in legacy code.
5555
56-
To access services that are not available through the `Utils`-service, inject or call them directly.
56+
```php
57+
use HeimrichHannot\UtilsBundle\Util\Utils;
58+
59+
class MyService {
60+
/** @var Utils */
61+
protected $utils;
62+
63+
public function __construct(Utils $utils) {
64+
$this->utils = $utils;
65+
}
66+
67+
public function someActions(): bool {
68+
return $this->utils->string()->startsWith('Lorem ipsum dolor sit amet', 'Lorem');
69+
}
70+
}
71+
```
72+
73+
To access services that are not available through the `Utils` service, inject or call them directly.
5774

58-
> Keep in mind that all services are about to be moved to the Utils namespace and will be deprecated (and removed in version 3.0) in the future.
75+
> [!IMPORTANT]
76+
> Keep in mind that all utils are on the brink of being moved to the `Utils`-service locator and won't be available through service tags in `v3`.
5977
78+
### Index of Available Services
6079

61-
Available [Service](src/Resources/config/services.yml) (as of version 2.131):
80+
Available [Services](src/Resources/config/services.yml) (as of version 2.131):
6281

6382
```
6483
huh.utils.accordion
@@ -165,7 +184,7 @@ DateAddedField::register('tl_example')
165184

166185
### Utils
167186

168-
[~~PdfCreator~~](docs/utils/pdf/pdfcreator.md) - ~~High-level API to create pdf files with PHP~~ (PDFCreator was moved into it's [own library](https://github.com/heimrichhannot/pdf-creator))
187+
~~[PdfCreatorx](docs/utils/pdf/pdfcreator.md) - High-level API to create pdf files with PHP~~ (PDFCreator has moved to its [own library](https://github.com/heimrichhannot/pdf-creator).)
169188

170189
### Using with Webpack/Encore
171190

@@ -185,22 +204,22 @@ static get(url, data, config) {...}
185204
```
186205
Both take the following parameters
187206

188-
name | description
189-
| --- | --- |
190-
| url | The url the request will be send to. |
191-
| data | The data that is used for the request. It has to be passed as JSON. |
207+
| name | description |
208+
|--------|---------------------------------------------------------------------------------------------------------------|
209+
| url | The url the request will be send to. |
210+
| data | The data that is used for the request. It has to be passed as JSON. |
192211
| config | An object that can hold the onSuccess-, onError-, beforeSubmit-, afterSubmit-callback and the request headers |
193212

194213

195214
Parameters of config
196215

197-
name | description
198-
| --- | --- |
199-
| onSuccess | Is called when the request was successfull. The request is passed as parameter. |
200-
| onError | Is called when the request had an error. The request is passed as parameter. |
216+
| name | description |
217+
|--------------|-----------------------------------------------------------------------------------------------|
218+
| onSuccess | Is called when the request was successful. The request is passed as parameter. |
219+
| onError | Is called when the request had an error. The request is passed as parameter. |
201220
| beforeSubmit | Is called before the request is submitted. The url, data and config are passed as parameters. |
202-
| afterSubmit | Is called before the request is submitted. The url, data and config are passed as parameters. |
203-
| headers | The headers will be set when the request is initialized. |
221+
| afterSubmit | Is called before the request is submitted. The url, data and config are passed as parameters. |
222+
| headers | The headers will be set when the request is initialized. |
204223

205224
The contents of the config parameter are all optional. If you pass an empty config to the ajaxUtil a silent request will be processed.
206225
The data will be transformed in the fitting format accordion wether you use a POST- or a GET-request.
@@ -210,10 +229,10 @@ To use the shorthands import the utilsBundle into your script. After that just c
210229
```
211230
import "@hundh/contao-utils-bundle";
212231
213-
...
232+
// ...
214233
215234
utilsBundle.ajax.get(url, data, config);
216-
# or
235+
// or
217236
utilsBundle.ajax.post(url, data, config);
218237
```
219238

@@ -241,27 +260,26 @@ huh_utils:
241260
242261
These bundle add server twig filters:
243262
244-
Filter | Parameter | Description
245-
----------------- | --------- | -----------
246-
autolink | array options | Create a link if string is an url.
247-
anonymize_email | - | Returns an anonymized email address. [email protected] will be max.****@example.org
248-
deserialize | bool force_array = false | Deserialize an serialized array (using `\Contao\StringUtil`)
249-
download | download = true, data = [], template = "@HeimrichHannotContaoUtils\/download.html.twig" |
250-
download_data | data = [] |
251-
download_link | data = [] |
252-
download_path | data = [] |
253-
download_title | data = [] |
254-
file_data | data = [], jsonSerializeOptions = []
255-
file_path | |
256-
image | size = null, data = [], template = "image.html.twig" |
257-
image_caption | |
258-
image_data | size = null, data = [] |
259-
image_gallery | template = "image_gallery.html.twig"
260-
image_size | |
261-
image_width | |
262-
localized_date | format = null |
263-
replace_inserttag | bool cache = true | Replace contao inserttag in twig string.
264-
263+
| Filter | Parameter | Description |
264+
|-------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
265+
| autolink | array options | Create a link if string is an url. |
266+
| anonymize_email | - | Returns an anonymized email address. [email protected] will be max.****@example.org |
267+
| deserialize | bool force_array = false | Deserialize an serialized array (using `\Contao\StringUtil`) |
268+
| download | download = true, data = [], template = "@HeimrichHannotContaoUtils\/download.html.twig" | |
269+
| download_data | data = [] | |
270+
| download_link | data = [] | |
271+
| download_path | data = [] | |
272+
| download_title | data = [] | |
273+
| file_data | data = [], jsonSerializeOptions = [] | |
274+
| file_path | | |
275+
| image | size = null, data = [], template = "image.html.twig" | |
276+
| image_caption | | |
277+
| image_data | size = null, data = [] | |
278+
| image_gallery | template = "image_gallery.html.twig" | |
279+
| image_size | | |
280+
| image_width | | |
281+
| localized_date | format = null | |
282+
| replace_inserttag | bool cache = true | Replace contao inserttag in twig string. |
265283

266284
### Image Extension
267285

@@ -292,9 +310,9 @@ Use the download extension to render download elements, get download links, down
292310
293311
## Insert tags
294312
295-
| Insert tag | Description |
296-
|---|---|
297-
| {{twig::*}} | This tag will be replaced with the rendered output of a given twig template, that can be sourced in `bundle/src/Resources/views` or contao root `/templates` directory (replace 1st * with template name e.g. `svg_logo_company` and 2nd * with serialized parameters that should be passed to the template) |
313+
| Insert tag | Description |
314+
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
315+
| {{twig::*}} | This tag will be replaced with the rendered output of a given twig template, that can be sourced in `bundle/src/Resources/views` or contao root `/templates` directory (replace 1st * with template name e.g. `svg_logo_company` and 2nd * with serialized parameters that should be passed to the template) |
298316
299317
## Commands
300318

0 commit comments

Comments
 (0)