From 7f1b73efee58e9123cfd21f4380c9610f7d4e949 Mon Sep 17 00:00:00 2001 From: Tom H Anderson Date: Tue, 29 Oct 2024 17:14:43 -0600 Subject: [PATCH] RST docs --- docs/blameable.md | 113 -------------------------------------- docs/blameable.rst | 35 ++++++++++++ docs/conf.py | 68 +++++++++++++++++++++++ docs/custom-functions.md | 74 ------------------------- docs/custom-functions.rst | 91 ++++++++++++++++++++++++++++++ docs/favicon.ico | Bin 0 -> 4286 bytes docs/footer.rst | 6 ++ docs/index.md | 19 ------- docs/index.rst | 27 +++++++++ docs/installation.md | 38 ------------- docs/installation.rst | 49 +++++++++++++++++ docs/introduction.md | 28 ---------- docs/introduction.rst | 59 ++++++++++++++++++++ docs/iptraceable.md | 86 ----------------------------- docs/iptraceable.rst | 34 ++++++++++++ docs/loggable.md | 58 ------------------- docs/loggable.rst | 30 ++++++++++ docs/lumen.md | 38 ------------- docs/requirements.txt | 1 + docs/sluggable.md | 62 --------------------- docs/sluggable.rst | 32 +++++++++++ docs/softdeletes.md | 54 ------------------ docs/softdeletes.rst | 35 ++++++++++++ docs/sortable.md | 57 ------------------- docs/sortable.rst | 30 ++++++++++ docs/timestamps.md | 94 ------------------------------- docs/timestamps.rst | 29 ++++++++++ docs/translatable.md | 108 ------------------------------------ docs/translatable.rst | 31 +++++++++++ docs/tree.md | 112 ------------------------------------- docs/tree.rst | 30 ++++++++++ docs/upgrade.md | 1 - docs/uploadable.md | 85 ---------------------------- docs/uploadable.rst | 28 ++++++++++ 34 files changed, 615 insertions(+), 1027 deletions(-) delete mode 100644 docs/blameable.md create mode 100644 docs/blameable.rst create mode 100644 docs/conf.py delete mode 100644 docs/custom-functions.md create mode 100644 docs/custom-functions.rst create mode 100644 docs/favicon.ico create mode 100644 docs/footer.rst delete mode 100644 docs/index.md create mode 100644 docs/index.rst delete mode 100644 docs/installation.md create mode 100644 docs/installation.rst delete mode 100644 docs/introduction.md create mode 100644 docs/introduction.rst delete mode 100644 docs/iptraceable.md create mode 100644 docs/iptraceable.rst delete mode 100644 docs/loggable.md create mode 100644 docs/loggable.rst delete mode 100644 docs/lumen.md create mode 100644 docs/requirements.txt delete mode 100644 docs/sluggable.md create mode 100644 docs/sluggable.rst delete mode 100644 docs/softdeletes.md create mode 100644 docs/softdeletes.rst delete mode 100644 docs/sortable.md create mode 100644 docs/sortable.rst delete mode 100644 docs/timestamps.md create mode 100644 docs/timestamps.rst delete mode 100644 docs/translatable.md create mode 100644 docs/translatable.rst delete mode 100644 docs/tree.md create mode 100644 docs/tree.rst delete mode 100644 docs/upgrade.md delete mode 100644 docs/uploadable.md create mode 100644 docs/uploadable.rst diff --git a/docs/blameable.md b/docs/blameable.md deleted file mode 100644 index 648b8c9..0000000 --- a/docs/blameable.md +++ /dev/null @@ -1,113 +0,0 @@ -# Blameable - -Blameable behavior will automate the update of username or user reference fields on your Entities or Documents. It works through annotations and can update fields on creation, update, property subset update, or even on specific property value change. - -* Automatic predefined user field update on creation, update, property subset update, and even on record property changes -* Specific annotations for properties, and no interface required -* Can react to specific property or relation changes to specific value -* Can be nested with other behaviors -* Annotation, Yaml and Xml mapping support for extensions - -### Installation - -Add `LaravelDoctrine\Extensions\Blameable\BlameableExtension` to `doctrine.extensions` config. - -### Property annotation - -> @Gedmo\Mapping\Annotation\Blameable - -This annotation tells that this column is blameable -by default it updates this column on update. If column is not a string field or an association -it will trigger an exception. - -Available configuration options: - -| Annotations | Description | -|--|--| -| **on** |is main option and can be **create, update, change** this tells when it should be updated| -| **field** | only valid if **on="change"** is specified, tracks property or a list of properties for changes | -| **value** | only valid if **on="change"** is specified and the tracked field is a single field (not an array), if the tracked field has this **value** then it updates the blame | - -Column is a string field: - -``` php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..00054d2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,68 @@ +import sys, os +from sphinx.highlighting import lexers +from pygments.lexers.web import PhpLexer + +lexers['php'] = PhpLexer(startinline=True, linenos=0) +lexers['php-annotations'] = PhpLexer(startinline=True, linenos=0) +primary_domain = 'php' + +extensions = [] +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' +project = u'Laravel Doctrine ORM Extensions' +copyright = u'2024 laraveldoctrine.org' +version = '9' +html_title = "Extensions for Laravel and Doctrine ORM" +html_short_title = "Laravel Doctrine ORM Extensions" +html_favicon = 'favicon.ico' + +exclude_patterns = ['_build'] +html_static_path = ['_static'] + +##### Guzzle sphinx theme + +import guzzle_sphinx_theme +html_translator_class = 'guzzle_sphinx_theme.HTMLTranslator' +html_theme_path = guzzle_sphinx_theme.html_theme_path() +html_theme = 'guzzle_sphinx_theme' + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + '**': ['logo-text.html', 'globaltoc.html', 'searchbox.html'] +} + +# Register the theme as an extension to generate a sitemap.xml +extensions.append("guzzle_sphinx_theme") + +# Guzzle theme options (see theme.conf for more information) +html_theme_options = { + + # Set the path to a special layout to include for the homepage + # "index_template": "homepage.html", + + # Allow a separate homepage from the master_doc + # homepage = index + + # Set the name of the project to appear in the nav menu + # "project_nav_name": "Guzzle", + + # Set your Disqus short name to enable comments + # "disqus_comments_shortname": "my_disqus_comments_short_name", + + # Set you GA account ID to enable tracking + # "google_analytics_account": "my_ga_account", + + # Path to a touch icon + # "touch_icon": "", + + # Specify a base_url used to generate sitemap.xml links. If not + # specified, then no sitemap will be built. + "base_url": "https://extensions.docs.laraveldoctrine.org" + + # Allow the "Table of Contents" page to be defined separately from "master_doc" + # tocpage = Contents + + # Allow the project link to be overriden to a custom URL. + # projectlink = http://myproject.url +} diff --git a/docs/custom-functions.md b/docs/custom-functions.md deleted file mode 100644 index 92caac5..0000000 --- a/docs/custom-functions.md +++ /dev/null @@ -1,74 +0,0 @@ -# Custom datetime functions - -A set of extensions to Doctrine 2 that add support for additional queryfunctions available in MySQL and Oracle. - -When `LaravelDoctrine\Extensions\BeberleiExtensionsServiceProvider::class` the following functions will be automatically registered. - -| DB | Functions | -|--|---------| -| MySQL | `ACOS, ASCII, ASIN, ATAN, ATAN2, BINARY, CEIL, CHAR_LENGTH, CONCAT_WS, COS, COT, COUNTIF, CRC32, DATE, DATE_FORMAT, DATEADD, DATEDIFF, DATESUB, DAY, DAYNAME, DEGREES, FIELD, FIND_IN_SET, FLOOR, FROM_UNIXTIME, GROUP_CONCAT, HOUR, IFELSE, IFNULL, LAST_DAY, MATCH_AGAINST, MD5, MINUTE, MONTH, MONTHNAME, NULLIF, PI, POWER, QUARTER, RADIANS, RAND, REGEXP, REPLACE, ROUND, SECOND, SHA1, SHA2, SIN, SOUNDEX, STD, STRTODATE, SUBSTRING_INDEX, TAN, TIME, TIMESTAMPADD, TIMESTAMPDIFF, UUID_SHORT, WEEK, WEEKDAY, YEAR` | -| Oracle | `DAY, MONTH, NVL, TODATE, TRUNC, YEAR` | -| Sqlite | `DATE, MINUTE, HOUR, DAY, WEEK, WEEKDAY, MONTH, YEAR, STRFTIME*` | - -Alternativly you can include the separate classes inside `config/doctrine` config file. Example: - -``` - [ - 'carbondate' => DoctrineExtensions\Types\CarbonDateType::class, - 'carbondatetime' => DoctrineExtensions\Types\CarbonDateTimeType::class, - 'carbondatetimetz' => DoctrineExtensions\Types\CarbonDateTimeTzType::class, - 'carbontime' => DoctrineExtensions\Types\CarbonTimeType::class - ], - /* - |-------------------------------------------------------------------------- - | Doctrine custom datetime functions - |-------------------------------------------------------------------------- - */ - 'custom_datetime_functions' => [ - 'DATEADD' => DoctrineExtensions\Query\Mysql\DateAdd::class, - 'DATEDIFF' => DoctrineExtensions\Query\Mysql\DateDiff::class - ], - /* - |-------------------------------------------------------------------------- - | Doctrine custom numeric functions - |-------------------------------------------------------------------------- - */ - 'custom_numeric_functions' => [ - 'ACOS' => DoctrineExtensions\Query\Mysql\Acos::class, - 'ASIN' => DoctrineExtensions\Query\Mysql\Asin::class, - 'ATAN' => DoctrineExtensions\Query\Mysql\Atan::class, - 'ATAN2' => DoctrineExtensions\Query\Mysql\Atan2::class, - 'COS' => DoctrineExtensions\Query\Mysql\Cos::class, - 'COT' => DoctrineExtensions\Query\Mysql\Cot::class, - 'DEGREES' => DoctrineExtensions\Query\Mysql\Degrees::class, - 'RADIANS' => DoctrineExtensions\Query\Mysql\Radians::class, - 'SIN' => DoctrineExtensions\Query\Mysql\Sin::class, - 'TAN' => DoctrineExtensions\Query\Mysql\Ta::class - ], - /* - |-------------------------------------------------------------------------- - | Doctrine custom string functions - |-------------------------------------------------------------------------- - */ - 'custom_string_functions' => [ - 'CHAR_LENGTH' => DoctrineExtensions\Query\Mysql\CharLength::class, - 'CONCAT_WS' => DoctrineExtensions\Query\Mysql\ConcatWs::class, - 'FIELD' => DoctrineExtensions\Query\Mysql\Field::class, - 'FIND_IN_SET' => DoctrineExtensions\Query\Mysql\FindInSet::class, - 'REPLACE' => DoctrineExtensions\Query\Mysql\Replace::class, - 'SOUNDEX' => DoctrineExtensions\Query\Mysql\Soundex::class, - 'STR_TO_DATE' => DoctrineExtensions\Query\Mysql\StrToDate::class - ], - -]; diff --git a/docs/custom-functions.rst b/docs/custom-functions.rst new file mode 100644 index 0000000..39f2a3a --- /dev/null +++ b/docs/custom-functions.rst @@ -0,0 +1,91 @@ +========================= +Custom Database Functions +========================= + +A set of extensions to Doctrine that add support for additional +queryfunctions available in MySQL, Oracle, and SQLite. + +When ``LaravelDoctrine\Extensions\BeberleiExtensionsServiceProvider::class`` +is included, the following functions will be automatically registered: + +.. list-table:: Query/Type Extensions + :widths: 25 75 + :header-rows: 1 + + * - Database + - Functions + * - MySQL + - ``ACOS, ASCII, ASIN, ATAN, ATAN2, BINARY, CEIL, CHAR_LENGTH, CONCAT_WS, COS, COT, COUNTIF, CRC32, DATE, DATE_FORMAT, DATEADD, DATEDIFF, DATESUB, DAY, DAYNAME, DEGREES, FIELD, FIND_IN_SET, FLOOR, FROM_UNIXTIME, GROUP_CONCAT, HOUR, IFELSE, IFNULL, LAST_DAY, MATCH_AGAINST, MD5, MINUTE, MONTH, MONTHNAME, NULLIF, PI, POWER, QUARTER, RADIANS, RAND, REGEXP, REPLACE, ROUND, SECOND, SHA1, SHA2, SIN, SOUNDEX, STD, STRTODATE, SUBSTRING_INDEX, TAN, TIME, TIMESTAMPADD, TIMESTAMPDIFF, UUID_SHORT, WEEK, WEEKDAY, YEAR`` + * - Oracle + - ``DAY, MONTH, NVL, TODATE, TRUNC, YEAR`` + * - Sqlite + - ``DATE, MINUTE, HOUR, DAY, WEEK, WEEKDAY, MONTH, YEAR, STRFTIME*`` + + +Alternativly you can include the separate classes inside `config/doctrine` config file. Example: + +.. code-block:: php + + return [ + + ... + + /* + |-------------------------------------------------------------------------- + | Doctrine custom types + |-------------------------------------------------------------------------- + */ + 'custom_types' => [ + 'carbondate' => DoctrineExtensions\Types\CarbonDateType::class, + 'carbondatetime' => DoctrineExtensions\Types\CarbonDateTimeType::class, + 'carbondatetimetz' => DoctrineExtensions\Types\CarbonDateTimeTzType::class, + 'carbontime' => DoctrineExtensions\Types\CarbonTimeType::class + ], + /* + |-------------------------------------------------------------------------- + | Doctrine custom datetime functions + |-------------------------------------------------------------------------- + */ + 'custom_datetime_functions' => [ + 'DATEADD' => DoctrineExtensions\Query\Mysql\DateAdd::class, + 'DATEDIFF' => DoctrineExtensions\Query\Mysql\DateDiff::class + ], + /* + |-------------------------------------------------------------------------- + | Doctrine custom numeric functions + |-------------------------------------------------------------------------- + */ + 'custom_numeric_functions' => [ + 'ACOS' => DoctrineExtensions\Query\Mysql\Acos::class, + 'ASIN' => DoctrineExtensions\Query\Mysql\Asin::class, + 'ATAN' => DoctrineExtensions\Query\Mysql\Atan::class, + 'ATAN2' => DoctrineExtensions\Query\Mysql\Atan2::class, + 'COS' => DoctrineExtensions\Query\Mysql\Cos::class, + 'COT' => DoctrineExtensions\Query\Mysql\Cot::class, + 'DEGREES' => DoctrineExtensions\Query\Mysql\Degrees::class, + 'RADIANS' => DoctrineExtensions\Query\Mysql\Radians::class, + 'SIN' => DoctrineExtensions\Query\Mysql\Sin::class, + 'TAN' => DoctrineExtensions\Query\Mysql\Ta::class + ], + /* + |-------------------------------------------------------------------------- + | Doctrine custom string functions + |-------------------------------------------------------------------------- + */ + 'custom_string_functions' => [ + 'CHAR_LENGTH' => DoctrineExtensions\Query\Mysql\CharLength::class, + 'CONCAT_WS' => DoctrineExtensions\Query\Mysql\ConcatWs::class, + 'FIELD' => DoctrineExtensions\Query\Mysql\Field::class, + 'FIND_IN_SET' => DoctrineExtensions\Query\Mysql\FindInSet::class, + 'REPLACE' => DoctrineExtensions\Query\Mysql\Replace::class, + 'SOUNDEX' => DoctrineExtensions\Query\Mysql\Soundex::class, + 'STR_TO_DATE' => DoctrineExtensions\Query\Mysql\StrToDate::class + ], + + ]; + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..a86424ebba5b0fb29b82219cfa3ce29c5361178b GIT binary patch literal 4286 zcmcgvX>3$g6uvD>i6o+EG)h>0pz=rm0Bxs3DH0`s3W;I@Dxw%v)I^jJF)W3)Q)m&S zEt^u720_4zEK0N}6lIgjDoOz@rGPB~q$p*vbI<2@-pr84%ybw{^);vWzPp_7EZ;rv zjxh=R>(a&Of3xy7W9~A>bfa*{^r7gu^KkBtwgCwY#Q#4nS4`S8X_4l$T|7SfBxMq1 zE@d7ii!zLJ_j6qa$PRrag6W-%qh zvBM`ZG{>GwFMy#QmD?$ksk=6W=WgjU1{GR7`kqA!?MTUTY`MTSv$^jcw#J)hV}pgw zrq8&JeJ}T~r1&Y0ukKdy#(ZpX@^_%J7Fe=P@bXfNzWI(FlAL8XrR3NLxX$#*ia!>P z-?_Fuu~xb9+S@pRV}kYjr5HdP zzDEMOMmoJi-qKF$PGft+2HRpk~dj-96ot!)QXUx@Sj3~C4!x-$T7PX_n z3WogUhoK!V#2dSP@`&$4i-GUk;(p|la!d6o9__gy|0{M0PG10qEeOoJ?bE*Q3E47o zvBjj%0V2XnX<_Z_LjiKBJE#)E>qje-{!1^BIcdrY-ZeP{oKRB6oJjfT7}9=BSY+-c53I#myO;po}* zt6QodU+#;bw2z-;;X=6ot%A*m1EPGUKV>O7 zl0+NA-8ZEb9P>09)={nTH*iX0pg77&)#*M9np=&HikIi`F~;cCl0d#SHp(4s_nr`} z*&}P8T_`Q5tc%3IBryFS~OdM<_ZtM7W=w8l^PG{B3{T(nm4l_xuX5%@L)*6TNk z@v+R|aOyMWsYw47Uu!SrPU@`)>F&)Om;EFtJ0#G)JNBV9?$*niwQPqtXCs~YaLpa( zx4f&yxT#0+Q?vXUhjHAe-!HsNKI`{I>#4@Vr7xnd^E_it-FW7Mz*>hFwCU-2w&<-= zBo3Gz-S?19!5nm89CvGd*~jl&IOm$OLHSqAbNM6d*0!VK)K7h%^_5h8aX=m{{Xt^Z zf3<;k9mDU5=|0syzMx#r9bny1PRHV$+a5iW18DbiA6krEB`Ew_8ury-l-3=m#)KS= z(Y~~lF&bzS>n>vS_)p~G&EoFH*S^}Sdl>sG^dqz5Slhbm_@?t7&6LS&#T0)hEg91h z)L9db5y$&k=5j1K*GBJ<|K?FXrspAndU_B~?_u?E;Of1!oO}9u^}ZaX*8Wpll#}#9 z@1bf#1n*sAdS6<>bscn1uj#S59*-SC>|3cfpQ88frtq(EZ4vEkuX_fRG{&Po<{FRQ z{c~+wV$P>Ty#ojBxkSuNT^p;u!~_eQ^!QkZco(GJ!ECPtaiaNto@-ubo?EHk&GmS* ziO*V1ofBhVpW^(`;P0d6f_C(HGOvdGA4UA@zqMSp93ghUhl`*&YF6x!GL0uW(2*as-czJ$OnFn&J8}VjRHc;{?U1@{S`Tyfl97+PEwYF)^h>PkZ zU`m4CK0$9X`3o)Msxh5a>Wyg^CP~%CBymjT`W)A`)AhPnMfIpYl((R6>No8uohca< MeuW5!Y|2jHZ-kf<%>V!Z literal 0 HcmV?d00001 diff --git a/docs/footer.rst b/docs/footer.rst new file mode 100644 index 0000000..2c9dae8 --- /dev/null +++ b/docs/footer.rst @@ -0,0 +1,6 @@ + +---------- + +This is documentation for +`laravel-doctrine/extensions `_. +Please add your ★ star to the project. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 0816cec..0000000 --- a/docs/index.md +++ /dev/null @@ -1,19 +0,0 @@ -- Prologue - - [Introduction](/docs/{{version}}/extensions/introduction) - - [Upgrade Guide](/docs/{{version}}/extensions/upgrade) -- Setup - - [Laravel](/docs/{{version}}/extensions/installation) - - [Lumen](/docs/{{version}}/extensions/lumen) -- Behavioral extensions - - [Blameable](/docs/{{version}}/extensions/blameable) - - [IpTraceable](/docs/{{version}}/extensions/iptraceable) - - [Loggable](/docs/{{version}}/extensions/loggable) - - [Sluggable](/docs/{{version}}/extensions/sluggable) - - [SoftDeletes](/docs/{{version}}/extensions/softdeletes) - - [Sortable](/docs/{{version}}/extensions/sortable) - - [Timestamps](/docs/{{version}}/extensions/timestamps) - - [Translatable](/docs/{{version}}/extensions/translatable) - - [Tree](/docs/{{version}}/extensions/tree) - - [Uploadable](/docs/{{version}}/extensions/uploadable) -- Query/Type extensions - - [Custom functions](/docs/{{version}}/extensions/custom-functions) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..0be618d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,27 @@ +=========================== +Laravel Doctrine Extensions +=========================== + +.. toctree:: + + :caption: Table of Contents + + introduction + installation + blameable + iptraceable + loggable + sluggable + softdeletes + sortable + timestamps + translatable + tree + uploadable + custom-functions + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 073789f..0000000 --- a/docs/installation.md +++ /dev/null @@ -1,38 +0,0 @@ -# Installation in Laravel 6+ - -Install this package with composer: - -``` -composer require laravel-doctrine/extensions -``` - -This package wraps extensions from [Gedmo](https://github.com/Atlantic18/DoctrineExtensions) and [Beberlei](https://github.com/beberlei/DoctrineExtensions). - -To include Gedmo extensions install them: - -``` - -composer require "gedmo/doctrine-extensions=^3.0" -``` - -If you are using an **annotation driver**, then add the Gedmo (Behavioral) extensions service provider in `config/app.php`: - -```php -LaravelDoctrine\Extensions\GedmoExtensionsServiceProvider::class, -``` - -Also be sure to enable the extensions in the `extensions` section of `config/doctrine.php`. - -To include Beberlei (Query/Type) extensions install them: - -``` - -composer require "beberlei/DoctrineExtensions=^1.0" -``` - -And then add the Beberlei extensions service provider in `config/app.php`: - - -```php -LaravelDoctrine\Extensions\BeberleiExtensionsServiceProvider::class, -``` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..6eebf37 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,49 @@ +============ +Installation +============ + +Install this package with composer: + +.. code-block:: bash + + composer require laravel-doctrine/extensions + +This package wraps extensions from `Gedmo `_ +and `Beberlei `_. + + +To include Gedmo extensions install them with composer: + +.. code-block:: bash + + composer require "gedmo/doctrine-extensions" + + +Enable the service provider for them in Laravel: + +.. code-block:: php + + LaravelDoctrine\Extensions\GedmoExtensionsServiceProvider::class + +Also, be sure to enable the extensions in the ``extensions`` section of +``config/doctrine.php``. + + +To include Beberlei (Query/Type) extensions install them: + +.. code-block:: bash + + composer require "beberlei/DoctrineExtensions=^1.0" + + +And then add the Beberlei extensions service provider in `config/app.php`: + +.. code-block:: php + + LaravelDoctrine\Extensions\BeberleiExtensionsServiceProvider::class + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/introduction.md b/docs/introduction.md deleted file mode 100644 index 269bf77..0000000 --- a/docs/introduction.md +++ /dev/null @@ -1,28 +0,0 @@ -# Introduction - -This package contains extensions for Doctrine2 that hook into the facilities of Doctrine and offer new functionality -or tools to use Doctrine2 more efficiently. This package contains mostly used behaviors which can be easily attached to your event system -of Doctrine2 and handle the records being flushed in the behavioral way - -### Behavioral extensions (Gedmo) - -* __Blameable__ - updates string or reference fields on create, update and even property change with a string or object (e.g. user). -* __IpTraceable__ - inherited from Timestampable, sets IP address instead of timestamp -* __Loggable__ - helps tracking changes and history of objects, also supports version management. -* __Sluggable__ - urlizes your specified fields into single unique slug -* __SoftDeleteable__ - allows to implicitly remove records -* __Sortable__ - makes any document or entity sortable -* __Timestampable__ - updates date fields on create, update and even property change. -* __Translatable__ - gives you a very handy solution for translating records into different languages. Easy to setup, easier to use. -* __Tree__ - this extension automates the tree handling process and adds some tree specific functions on repository. (closure, nestedset or materialized path) -* __Uploadable__ - provides file upload handling in entity fields - -### Query/Type extensions (Beberlei) - -A set of extensions to Doctrine 2 that add support for additional queryfunctions available in MySQL and Oracle. - -| DB | Functions | -|--|---------| -| MySQL | `ACOS, ASCII, ASIN, ATAN, ATAN2, BINARY, CEIL, CHAR_LENGTH, CONCAT_WS, COS, COT, COUNTIF, CRC32, DATE, DATE_FORMAT, DATEADD, DATEDIFF, DATESUB, DAY, DAYNAME, DEGREES, FIELD, FIND_IN_SET, FLOOR, FROM_UNIXTIME, GROUP_CONCAT, HOUR, IFELSE, IFNULL, LAST_DAY, MATCH_AGAINST, MD5, MINUTE, MONTH, MONTHNAME, NULLIF, PI, POWER, QUARTER, RADIANS, RAND, REGEXP, REPLACE, ROUND, SECOND, SHA1, SHA2, SIN, SOUNDEX, STD, STRTODATE, SUBSTRING_INDEX, TAN, TIME, TIMESTAMPADD, TIMESTAMPDIFF, UUID_SHORT, WEEK, WEEKDAY, YEAR` | -| Oracle | `DAY, MONTH, NVL, TODATE, TRUNC, YEAR` | -| Sqlite | `DATE, MINUTE, HOUR, DAY, WEEK, WEEKDAY, MONTH, YEAR, STRFTIME*` | diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..640d037 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,59 @@ +============ +Introduction +============ + +This package contains extensions for Doctrine that hook into the facilities +of Doctrine and offer new functionality and tools to use Doctrine +more efficiently. This package contains mostly used behaviors which can be +easily attached to the event system of Doctrine to handle records being +flushed in a behavioral way. + +Behavioral extensions (Gedmo) +============================= + +See the `doctrine-extensions documentation `_ +for more information. + +* ``Blameable`` - updates string or reference fields on create, update, and + even property change with a string or object (e.g. user). +* ``IpTraceable`` - inherited from Timestampable, sets IP address instead + of timestamp. +* ``Loggable`` - helps tracking changes and history of objects, also supports + version management. +* ``Sluggable`` - urlizes your specified fields into single unique slug. +* ``SoftDeleteable`` - allows to implicitly remove records. +* ``Sortable`` - makes any document or entity sortable. +* ``Timestampable`` - updates date fields on create, update, and even + property change. +* ``Translatable`` - gives you a handy solution for translating records into + different languages. Easy to setup, easier to use. +* ``Tree`` - this extension automates the tree handling process and adds + some tree specific functions on repository. (closure, nestedset or + materialized path). +* ``Uploadable`` - provides file upload handling in entity fields. + + +Query/Type Extensions (Beberlei) +================================ + +A set of extensions for Doctrine that add support for additional functions +available in MySQL and Oracle. + +.. list-table:: Query/Type Extensions + :widths: 25 75 + :header-rows: 1 + + * - Database + - Functions + * - MySQL + - ``ACOS, ASCII, ASIN, ATAN, ATAN2, BINARY, CEIL, CHAR_LENGTH, CONCAT_WS, COS, COT, COUNTIF, CRC32, DATE, DATE_FORMAT, DATEADD, DATEDIFF, DATESUB, DAY, DAYNAME, DEGREES, FIELD, FIND_IN_SET, FLOOR, FROM_UNIXTIME, GROUP_CONCAT, HOUR, IFELSE, IFNULL, LAST_DAY, MATCH_AGAINST, MD5, MINUTE, MONTH, MONTHNAME, NULLIF, PI, POWER, QUARTER, RADIANS, RAND, REGEXP, REPLACE, ROUND, SECOND, SHA1, SHA2, SIN, SOUNDEX, STD, STRTODATE, SUBSTRING_INDEX, TAN, TIME, TIMESTAMPADD, TIMESTAMPDIFF, UUID_SHORT, WEEK, WEEKDAY, YEAR`` + * - Oracle + - ``DAY, MONTH, NVL, TODATE, TRUNC, YEAR`` + * - Sqlite + - ``DATE, MINUTE, HOUR, DAY, WEEK, WEEKDAY, MONTH, YEAR, STRFTIME*`` + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/iptraceable.md b/docs/iptraceable.md deleted file mode 100644 index e326875..0000000 --- a/docs/iptraceable.md +++ /dev/null @@ -1,86 +0,0 @@ -# Ip Traceable - -IpTraceable behavior will automate the update of IP trace on your Entities or Documents. It works through annotations and can update fields on creation, update, property subset update, or even on specific property value change. - -* Automatic predefined ip field update on creation, update, property subset update, and even on record property changes -* Specific annotations for properties, and no interface required -* Can react to specific property or relation changes to specific value -* Can be nested with other behaviors -* Annotation, Yaml and Xml mapping support for extensions - -### Installation - -Add `LaravelDoctrine\Extensions\IpTraceable\IpTraceableExtension` to `doctrine.extensions` config. - -### Property annotation - -> @Gedmo\Mapping\Annotation\IpTraceable - -This annotation tells that this column is ipTraceable by default it updates this column on update. If column is not a string field it will trigger an exception. - -Available configuration options: - -| Annotations | Description | -|--|--| -| **on** |is main option and can be **create, update, change** this tells when itshould be updated| -| **field** | only valid if **on="change"** is specified, tracks property or a list of properties for changes | -| **value** | only valid if **on="change"** is specified and the tracked field is a single field (not an array), if the tracked field has this **value**then it updates the trace | - -``` php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/loggable.md b/docs/loggable.md deleted file mode 100644 index 37ed871..0000000 --- a/docs/loggable.md +++ /dev/null @@ -1,58 +0,0 @@ -# Loggable - -**Loggable** behavior tracks your record changes and is able to manage versions. - -- Automatic storage of log entries in database -- Can be nested with other behaviors -- Objects can be reverted to previous versions -- Annotation, Yaml and Xml mapping support for extensions - -### Installation - -Add `LaravelDoctrine\Extensions\Loggable\LoggableExtension` to `doctrine.extensions` config. - -### Class annotation - -> @Gedmo\Mapping\Annotation\Loggable() - -This class annotation will store logs to optionally specified logEntryClass. - -| Annotations | Description | -|--|--| -| **logEntryClass** |optional entity which stores logs| - -### Property annotation - ->@Gedmo\Mapping\Annotation\Versioned - -This property annotation tracks annotated property for changes - -``` php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/lumen.md b/docs/lumen.md deleted file mode 100644 index f2231aa..0000000 --- a/docs/lumen.md +++ /dev/null @@ -1,38 +0,0 @@ -# Installation in Lumen 6+ - -To set up Laravel Doctrine Extensions in Lumen, we need some additional steps. - -Install this package with composer: - -``` -composer require laravel-doctrine/extensions -``` - -After updating composer, open `bootstrap/app.php` and register the Service Provider after `LaravelDoctrine\ORM\DoctrineServiceProvider::class` - - -To include Gedmo extensions install them: - -``` - -composer require "gedmo/doctrine-extensions=^3.0" -``` - -If you are using an **annotation driver**, then add the Gedmo (Behavioral) extensions service provider in `config/app.php`: - -```php -$app->register(LaravelDoctrine\Extensions\GedmoExtensionsServiceProvider::class), -``` - -To include Beberlei (Query/Type) extensions install them: - -``` - -composer require "beberlei/DoctrineExtensions=^1.0" -``` - -And then add the Beberlei extensions service provider in `bootstrap/app.php`: - - -```php -$app->register(LaravelDoctrine\Extensions\BeberleiExtensionsServiceProvider::class), diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..a1540a8 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +guzzle_sphinx_theme diff --git a/docs/sluggable.md b/docs/sluggable.md deleted file mode 100644 index eb0b5c0..0000000 --- a/docs/sluggable.md +++ /dev/null @@ -1,62 +0,0 @@ -# Sluggable - -Sluggable behavior will build the slug of predefined fields on a given field which should store the slug - -- Automatic predefined field transformation into slug -- Slugs can be unique and styled, even with prefixes and/or suffixes -- Can be nested with other behaviors -- Annotation, Yaml and Xml mapping support for extensions -- Multiple slugs, different slugs can link to same fields - -### Installation - -Add `LaravelDoctrine\Extensions\Sluggable\SluggableExtension` to `doctrine.extensions` config. - -### Property annotation - -> @Gedmo\Mapping\Annotation\Slug - -This annotation will use the column to store slug generated fields option must be specified, an array of field names to slug - -| Annotations | Description | -|--|--| -| **fields** | array of fields that should be slugged | - -``` php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/softdeletes.md b/docs/softdeletes.md deleted file mode 100644 index 51c9175..0000000 --- a/docs/softdeletes.md +++ /dev/null @@ -1,54 +0,0 @@ -# SoftDeletes - -SoftDeleteable behavior allows to "soft delete" objects, filtering them at SELECT time by marking them as with a timestamp, but not explicitly removing them from the database. - -- Works with DQL DELETE queries (using a Query Hint). -- All SELECT queries will be filtered, not matter from where they are executed (Repositories, DQL SELECT queries, etc). -- Can be nested with other behaviors -- Annotation, Yaml and Xml mapping support for extensions -- Support for 'timeAware' option: When creating an entity set a date of deletion in the future and never worry about cleaning up at expiration time. - -### Installation - -Add `LaravelDoctrine\Extensions\SoftDeletes\SoftDeleteableExtension` to `doctrine.extensions` config. - -### Class annotation - -> @Gedmo\Mapping\Annotation\SoftDeleteable - -This class annotation tells if a class is SoftDeleteable. It has a mandatory parameter "fieldName", which is the name of the field to be used to hold the known "deletedAt" field. It must be of any of the date types. - -| Annotations | Description | -|--|--| -| **fieldName** | The name of the field that will be used to determine if the object is removed or not (NULL means it's not removed. A date value means it was removed). NOTE: The field MUST be nullable. | - -``` php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/sortable.md b/docs/sortable.md deleted file mode 100644 index 8e02ca2..0000000 --- a/docs/sortable.md +++ /dev/null @@ -1,57 +0,0 @@ -# Sortable - -**Sortable** behavior will maintain a position field for ordering entities. - -- Automatic handling of position index -- Group entity ordering by one or more fields -- Can be nested with other behaviors -- Annotation, Yaml and Xml mapping support for extensions - -### Installation - -Add `LaravelDoctrine\Extensions\Sortable\SortableExtension` to `doctrine.extensions` config. - -### Property annotation - -> @Gedmo\Mapping\Annotation\SortableGroup - -This annotation will be used for grouping - -> @Gedmo\Mapping\Annotation\SortablePosition - -This annotation will be used to store position index - -``` php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/timestamps.md b/docs/timestamps.md deleted file mode 100644 index 67abafa..0000000 --- a/docs/timestamps.md +++ /dev/null @@ -1,94 +0,0 @@ -# Timestamps - -Timestamps allows you to automatically record the time of certain events against your entities. This can be used -to provide similar behaviour to the timestamps feature in Laravel's Eloquent ORM. - -Features: - -* Automatic predefined date field update on creation, update, property subset update, and even on record property changes -* Specific annotations for properties, and no interface required -* Can react to specific property or relation changes to specific value -* Can be nested with other behaviors -* Annotation, Yaml and Xml mapping support for extensions - -### Property annotation - -> @Gedmo\Mapping\Annotation\Timestampable - -This annotation tells that this column is timestampable by default it updates this column on update. If column is not date, datetime or time type it will trigger an exception. - -| Annotations | Description | -|--|--| -| **on** | is main option and can be create, update, change this tells when it should be updated | -| **field** | only valid if on="change" is specified, tracks property or a list of properties for changes | -| **value** | only valid if on="change" is specified and the tracked field is a single field (not an array), if the tracked field has this value | - -```php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/translatable.md b/docs/translatable.md deleted file mode 100644 index 38c099f..0000000 --- a/docs/translatable.md +++ /dev/null @@ -1,108 +0,0 @@ -# Translatable - -Translatable behavior offers a very handy solution for translating specific record fields in different languages. Further more, it loads the translations automatically for a locale currently used, which can be set to Translatable Listener on it`s initialization or later for other cases through the Entity itself - -Features: - -- Automatic storage of translations in database -- Automatic translation of Entity or Document fields then loaded -- ORM query can use **hint** to translate all records without issuing additional queries -- Can be nested with other behaviors -- Annotation, Yaml and Xml mapping support for extensions - -### Class annotation - -> @Gedmo\Mapping\Annotation\Translatable - -| Annotations | Description | -|--|--| -| **class** | it will use this class to store translations generated | - -### Property annotation - -> @Gedmo\Mapping\Annotation\Translatable - -It will translate this field - -> @Gedmo\Mapping\Annotation\Locale or @Gedmo\Mapping\Annotation\Language - -This will identify this column as locale or language used to override the global locale - -```php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/tree.md b/docs/tree.md deleted file mode 100644 index 499342d..0000000 --- a/docs/tree.md +++ /dev/null @@ -1,112 +0,0 @@ -# Tree - Nestedset - -Tree nested behavior will implement the standard Nested-Set behavior on your Entity. Tree supports different strategies. Currently it supports nested-set, closure-table and materialized-path. Also this behavior can be nested with other extensions to translate or generated slugs of your tree nodes. - -- Materialized Path strategy for ORM -- Closure tree strategy, may be faster in some cases where ordering does not matter -- Support for multiple roots in nested-set -- No need for other managers, implementation is through event listener -- Synchronization of left, right values is automatic -- Can support concurrent flush with many objects being persisted and updated -- Can be nested with other extensions -- Annotation, Yaml and Xml mapping support for extensions - -### Class annotation - -> @Gedmo\Mapping\Annotation\Tree - -| Annotations | Description | -|--|--| -| **type** | this class annotation sets the tree strategy by using the type parameter. Currently nested, closure or materializedPath strategies are supported. An additional "activateLocking" parameter is available if you use the "Materialized Path" strategy with MongoDB. It's used to activate the locking mechanism (more on that in the corresponding section). | - -### Property annotation - -> @Gedmo\Mapping\Annotation\TreeLeft - -This field is used to store the tree left value - -> @Gedmo\Mapping\Annotation\TreeRight - -This field is used to store the tree right value - -> @Gedmo\Mapping\Annotation\TreeParent - -This will identify the column as the relation to parent node - -> @Gedmo\Mapping\Annotation\TreeLevel - -This field is used to store the tree level - -> @Gedmo\Mapping\Annotation\TreeRoot - -This field is used to store the tree root id value - -> @Gedmo\Mapping\Annotation\TreePath - -(Materialized Path only) This field is used to store the path. It has an optional parameter "separator" to define the separator used in the path. - -> @Gedmo\Mapping\Annotation\TreePathSource - -(Materialized Path only) This field is used as the source to construct the "path" - -```php -`_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst diff --git a/docs/upgrade.md b/docs/upgrade.md deleted file mode 100644 index 40e1497..0000000 --- a/docs/upgrade.md +++ /dev/null @@ -1 +0,0 @@ -# Upgrade Guide diff --git a/docs/uploadable.md b/docs/uploadable.md deleted file mode 100644 index 4299a66..0000000 --- a/docs/uploadable.md +++ /dev/null @@ -1,85 +0,0 @@ -# Uploadable - -Uploadable behavior provides the tools to manage the persistence of files with Doctrine 2, including automatic handling of moving, renaming and removal of files and other features. - -- Extension moves, removes and renames files according to configuration automatically -- Lots of options: Allow overwrite, append a number if file exists, filename generators, post-move callbacks, etc. -- It can be extended to work not only with uploaded files, but with files coming from any source (an URL, another - file in the same server, etc). -- Validation of size and mime type - -### Class annotation - -> @Gedmo\Mapping\Annotation\Uploadable - -This class annotation tells if a class is Uploadable. - -| Annotations | Description | -|--|--| -|**allowOverwrite** | If this option is true, it will overwrite a file if it already exists. If you set "false", an exception will be thrown. Default: false| -|**appendNumber** | If this option is true and "allowOverwrite" is false, in the case that the file already exists, it will append a number to the filename. Example: if you're uploading a file named "test.txt", if the file already exists and this option is true, the extension will modify the name of the uploaded file to "test1.txt", where "1" could be any number. The extension will check if the file exists until it finds a filename with a number as its postfix that is not used. If you use a filename generator and this option is true, it will append a number to the filename anyway if a file with the same name already exists. Default value: false| -|**path** | This option expects a string containing the path where the files represented by this entity will be moved. Default: "". Path can be set in other ways: From the listener or from a method. More details later.| -|**pathMethod** | Similar to option "path", but this time it represents the name of a method on the entity that will return the path to which the files represented by this entity will be moved. This is useful in several cases. For example, you can set specific paths for specific entities, or you can get the path from other sources (like a framework configuration) instead of hardcoding it in the entity. Default: "". As first argument this method takes default path, so you can return path relative to default.| -|**callback** | This option allows you to set a method name. If this option is set, the method will be called after the file is moved. Default value: "". As first argument, this method can receive an array with information about the uploaded file, which includes the following keys: **fileName:**, **fileExtension**, **fileWithoutExt**, **filePath**, **fileMimeType**, **fileSize** .| -|**filenameGenerator**| This option allows you to set a filename generator for the file. There are two already included by the extension: SHA1, which generates a sha1 filename for the file, and ALPHANUMERIC, which "normalizes" the filename, leaving only alphanumeric characters in the filename, and replacing anything else with a "-". You can even create your own FilenameGenerator class (implementing the Gedmo\Uploadable\FilenameGenerator\FilenameGeneratorInterface) and set this option with the fully qualified class name. The other option available is "NONE" which, as you may guess, means no generation for the filename will occur. Default: "NONE".| -|**maxSize**| This option allows you to set a maximum size for the file in bytes. If file size exceeds the value set in this configuration, an exception of type "UploadableMaxSizeException" will be thrown. By default, its value is set to 0, meaning that no size validation will occur.| -|**allowedTypes**| With this option you can set a comma-separated list of allowed mime types for the file. The extension will use a simple mime type guesser to guess the file type, and then it will compare it to the list of allowed types. If the mime type is not valid, then an exception of type "UploadableInvalidMimeTypeException" will be thrown. If you set this option, you can't set the disallowedTypes option described next. By default, no validation of mime type occurs. If you want to use a custom mime type guesser, see this.| -|**disallowedTypes**| Similar to the option allowedTypes, but with this one you configure a "black list" of mime types. If the mime type of the file is on this list, n exception of type "UploadableInvalidMimeTypeException" will be thrown. If you set this option, you can't set the allowedTypes option described next. By default, no validation of mime type occurs. If you want to use a custom mime type guesser, see this.| - -### Property annotation - -> @Gedmo\Mapping\Annotation\UploadableFilePath - -This annotation is used to set which field will receive the path to the file. The field MUST be of type "string". Either this one or UploadableFileName annotation is REQUIRED to be set. - -> @Gedmo\Mapping\Annotation\UploadableFileName - -This annotation is used to set which field will receive the name of the file. The field MUST be of type "string". Either this one or UploadableFilePath annotation is REQUIRED to be set. - -> @Gedmo\Mapping\Annotation\UploadableFileMimeType - -This is an optional annotation used to set which field will receive the mime type of the file as its value. This field MUST be of type "string". - -> @Gedmo\Mapping\Annotation\UploadableFileSize - -This is an optional annotation used to set which field will receive the size in bytes of the file as its value. This field MUST be of type "decimal". - - -```php -addEntityFileInto($entity, $fileInfo); -``` - -Another way would be to also register the `LaravelDoctrine\Extensions\Uploadable\UploadableFacade::class` facade in the `aliases` array in the Laravel's `app.php`. Then you can use the facade to call the listener's methods. - -Example with a facade (named `Uploadable`): -``` -\Uploadable::addEntityFileInfo($entity, $fileInfo); -``` - - -For full documentation see [here.](https://github.com/Atlantic18/DoctrineExtensions/blob/master/doc/uploadable.md) diff --git a/docs/uploadable.rst b/docs/uploadable.rst new file mode 100644 index 0000000..d8b2fb2 --- /dev/null +++ b/docs/uploadable.rst @@ -0,0 +1,28 @@ +========== +Uploadable +========== + +Uploadable behavior provides the tools to manage the persistence of files +with Doctrine, including automatic handling of moving, renaming and +removal of files and other features. + +* Extension moves, removes and renames files according to configuration + automatically. +* Lots of options: Allow overwrite, append a number if file exists, +* filename generators, post-move callbacks, etc. +* It can be extended to work not only with uploaded files, but with files +* coming from any source (an URL, another file in the same server, etc). +* Validation of size and mime type. + + +Further Reading +=============== + +See the `official documentation `_ +for use of this behavior. + + +.. role:: raw-html(raw) + :format: html + +.. include:: footer.rst