From a0773b2c787c4de019372337ece4a4836d7db07f Mon Sep 17 00:00:00 2001 From: Andrey Helldar Date: Sat, 6 Sep 2025 02:41:04 +0300 Subject: [PATCH 1/2] Added and updated documentation for `directives`, `location`, and `eloquent` topics --- docs/laravel-feeds.tree | 7 +- docs/snippets/advanced-directive-array.xml | 20 +- .../advanced-directive-attributes.xml | 10 +- docs/snippets/advanced-directive-cdata.xml | 8 +- docs/snippets/advanced-directive-mixed.xml | 8 +- docs/snippets/advanced-directive-value.xml | 8 +- docs/snippets/advanced-element-attribute.xml | 8 +- .../advanced-element-header-footer.xml | 4 +- .../advanced-element-info-before-false.xml | 4 +- docs/snippets/advanced-element-info.xml | 4 +- docs/snippets/advanced-element-root.xml | 4 +- docs/snippets/receipt-instagram-feed.xml | 48 ++-- docs/snippets/receipt-sitemap-feed.xml | 4 +- docs/snippets/receipt-yandex-feed.xml | 48 ++-- docs/topics/advanced-usage.topic | 267 ------------------ docs/topics/create-feeds.topic | 2 +- docs/topics/directives.topic | 133 +++++++++ docs/topics/elements.topic | 111 ++++++++ docs/topics/eloquent.topic | 23 ++ docs/topics/introduction.topic | 8 +- docs/topics/location.topic | 36 +++ 21 files changed, 404 insertions(+), 361 deletions(-) delete mode 100644 docs/topics/advanced-usage.topic create mode 100644 docs/topics/directives.topic create mode 100644 docs/topics/elements.topic create mode 100644 docs/topics/eloquent.topic create mode 100644 docs/topics/location.topic diff --git a/docs/laravel-feeds.tree b/docs/laravel-feeds.tree index 1739284..ba11aa3 100644 --- a/docs/laravel-feeds.tree +++ b/docs/laravel-feeds.tree @@ -17,10 +17,13 @@ - - + + + + + diff --git a/docs/snippets/advanced-directive-array.xml b/docs/snippets/advanced-directive-array.xml index 4180cc7..2934e8c 100644 --- a/docs/snippets/advanced-directive-array.xml +++ b/docs/snippets/advanced-directive-array.xml @@ -2,18 +2,18 @@ - Jaiden Gerhold - https://via.placeholder.com/640x480.png/0022dd?text=aut - https://via.placeholder.com/640x480.png/00ddff?text=quia - https://via.placeholder.com/640x480.png/004400?text=enim - https://via.placeholder.com/640x480.png/0011ff?text=eveniet + Dr. Domenic Howell III + https://via.placeholder.com/640x480.png/00cc77?text=sed + https://via.placeholder.com/640x480.png/000077?text=aut + https://via.placeholder.com/640x480.png/005511?text=aut + https://via.placeholder.com/640x480.png/00dd99?text=sint - Darien Murazik - https://via.placeholder.com/640x480.png/007700?text=vel - https://via.placeholder.com/640x480.png/00ffcc?text=nulla - https://via.placeholder.com/640x480.png/0022aa?text=dolore - https://via.placeholder.com/640x480.png/006611?text=dolorum + Dr. Cleveland Ryan + https://via.placeholder.com/640x480.png/001177?text=veritatis + https://via.placeholder.com/640x480.png/0066bb?text=dolorem + https://via.placeholder.com/640x480.png/00ffcc?text=quasi + https://via.placeholder.com/640x480.png/00dd33?text=officia diff --git a/docs/snippets/advanced-directive-attributes.xml b/docs/snippets/advanced-directive-attributes.xml index 1d66839..f6d38f5 100644 --- a/docs/snippets/advanced-directive-attributes.xml +++ b/docs/snippets/advanced-directive-attributes.xml @@ -1,16 +1,16 @@ - + https://example.com - Estell Reinger - + Emelia Kessler + - Mrs. Marilie O'Connell DDS - + Mr. Gerardo Cruickshank + diff --git a/docs/snippets/advanced-directive-cdata.xml b/docs/snippets/advanced-directive-cdata.xml index e12c72f..b90f5e4 100644 --- a/docs/snippets/advanced-directive-cdata.xml +++ b/docs/snippets/advanced-directive-cdata.xml @@ -2,12 +2,12 @@ - Jay Willms MD]]> - uerdman@example.net + Alfred Glover]]> + crooks.makayla@example.net - Mrs. Fae Rice]]> - kuhic.tristian@example.com + Arno Nader]]> + ofarrell@example.org diff --git a/docs/snippets/advanced-directive-mixed.xml b/docs/snippets/advanced-directive-mixed.xml index 0ca9879..b98e02f 100644 --- a/docs/snippets/advanced-directive-mixed.xml +++ b/docs/snippets/advanced-directive-mixed.xml @@ -2,17 +2,17 @@ - Heath Cummerata + Dr. Tom Schaefer II Foo - kasey.sawayn@example.org + brenna44@example.org - Dr. Levi Leannon + Vena Streich Foo - melany.runolfsson@example.org + bechtelar.richmond@example.com diff --git a/docs/snippets/advanced-directive-value.xml b/docs/snippets/advanced-directive-value.xml index 045bdd2..2d1363d 100644 --- a/docs/snippets/advanced-directive-value.xml +++ b/docs/snippets/advanced-directive-value.xml @@ -2,12 +2,12 @@ - Mr. Jo Emard DVM - carolina77@example.net + Gerda Bogisich + allie.heidenreich@example.net - Nicola Moore - lkuhlman@example.com + Trycia Connelly + ole.hayes@example.net diff --git a/docs/snippets/advanced-element-attribute.xml b/docs/snippets/advanced-element-attribute.xml index d9e6dad..35df1ae 100644 --- a/docs/snippets/advanced-element-attribute.xml +++ b/docs/snippets/advanced-element-attribute.xml @@ -1,13 +1,13 @@ - + 1 - Candida West + Dr. Colin Thiel - + 2 - Prof. Hilton Wuckert + Helga Auer diff --git a/docs/snippets/advanced-element-header-footer.xml b/docs/snippets/advanced-element-header-footer.xml index e6563ba..3c1c09b 100644 --- a/docs/snippets/advanced-element-header-footer.xml +++ b/docs/snippets/advanced-element-header-footer.xml @@ -3,11 +3,11 @@ 1 - Daija Powlowski + Emmy Dickens 2 - Lisa Reichel + Abraham Satterfield diff --git a/docs/snippets/advanced-element-info-before-false.xml b/docs/snippets/advanced-element-info-before-false.xml index 71ca29c..e4bf8a2 100644 --- a/docs/snippets/advanced-element-info-before-false.xml +++ b/docs/snippets/advanced-element-info-before-false.xml @@ -6,11 +6,11 @@ 1 - Tabitha Jakubowski + Vidal Runte 2 - Dr. Rachel Goyette + Marlee Breitenberg diff --git a/docs/snippets/advanced-element-info.xml b/docs/snippets/advanced-element-info.xml index 7ea6780..9d08d5b 100644 --- a/docs/snippets/advanced-element-info.xml +++ b/docs/snippets/advanced-element-info.xml @@ -6,11 +6,11 @@ 1 - Daija Wehner Jr. + Mr. Milan Parker 2 - Rosella Emard DDS + Prof. Irving Kuvalis diff --git a/docs/snippets/advanced-element-root.xml b/docs/snippets/advanced-element-root.xml index f794228..53daff3 100644 --- a/docs/snippets/advanced-element-root.xml +++ b/docs/snippets/advanced-element-root.xml @@ -3,11 +3,11 @@ 1 - Baby McDermott DDS + Zechariah Greenholt 2 - Rachael Jerde + Isaiah Hill I diff --git a/docs/snippets/receipt-instagram-feed.xml b/docs/snippets/receipt-instagram-feed.xml index 0f872f2..7fdf2f6 100644 --- a/docs/snippets/receipt-instagram-feed.xml +++ b/docs/snippets/receipt-instagram-feed.xml @@ -6,46 +6,46 @@ 1 - - - https://example.com/products/illo-fugiat-in-voluptatem-sunt - https://via.placeholder.com/640x480.png/00ff55?text=debitis - https://via.placeholder.com/640x480.png/001111?text=sequi - https://via.placeholder.com/640x480.png/00dd22?text=et - cupiditate + + + https://example.com/products/laborum-non-autem-nemo-laboriosam-vel + https://via.placeholder.com/640x480.png/009955?text=doloremque + https://via.placeholder.com/640x480.png/00bb00?text=voluptatem + https://via.placeholder.com/640x480.png/00bbdd?text=ut + ex new in stock - 348 - 348 + 103 + 103 12345 active - - 45 + + 17 adult - + 1000 2000 2 - - - https://example.com/products/laboriosam-hic-facilis-earum-voluptatem-sint-sit - https://via.placeholder.com/640x480.png/00bb77?text=autem - https://via.placeholder.com/640x480.png/00aa33?text=est - https://via.placeholder.com/640x480.png/002266?text=et - expedita + + + https://example.com/products/deserunt-dicta-reiciendis-dolores-neque-mollitia + https://via.placeholder.com/640x480.png/0088dd?text=hic + https://via.placeholder.com/640x480.png/0011cc?text=molestiae + https://via.placeholder.com/640x480.png/00bb11?text=eum + minus new in stock - 331 - 331 + 990 + 990 12345 active - - 46 + + 23 adult - + 1000 2000 diff --git a/docs/snippets/receipt-sitemap-feed.xml b/docs/snippets/receipt-sitemap-feed.xml index 067b8f4..21e25bd 100644 --- a/docs/snippets/receipt-sitemap-feed.xml +++ b/docs/snippets/receipt-sitemap-feed.xml @@ -2,12 +2,12 @@ - https://example.com/products/sunt-aut-eum-hic-enim-veritatis-libero + https://example.com/products/et-dolor-rerum-maxime-qui 2025-09-04T04:08:12+00:00 0.9 - https://example.com/products/rerum-est-ipsum-est-et-alias-commodi-neque-quod + https://example.com/products/quibusdam-nisi-minima-facere-nostrum-consequatur-eligendi-natus 2025-09-04T04:08:12+00:00 0.9 diff --git a/docs/snippets/receipt-yandex-feed.xml b/docs/snippets/receipt-yandex-feed.xml index a7ab487..8d89aa9 100644 --- a/docs/snippets/receipt-yandex-feed.xml +++ b/docs/snippets/receipt-yandex-feed.xml @@ -17,36 +17,36 @@ - https://example.com/products/fugiat-aut-sequi-minima-quia-facere - GD-O)N->X - adipisci quis asperiores rem - Cumque necessitatibus quia minima aspernatur et dolor quae. Dignissimos maxime aut rerum velit perspiciatis. Beatae sit a quisquam atque. + https://example.com/products/odit-error-voluptates-blanditiis-saepe-placeat + GD-+/ADU|]W + nam suscipit dolor dignissimos + Quasi magni consectetur quis. Nulla sunt vero vel quia qui autem. Qui aut quo enim quisquam et laudantium. Eos facilis autem sint asperiores temporibus. true - 456 + 708 RUR - eos - https://via.placeholder.com/640x480.png/00ff77?text=facere - https://via.placeholder.com/640x480.png/006622?text=illo - https://via.placeholder.com/640x480.png/00cc77?text=magni - GD-O)N->X - 2 - female + animi + https://via.placeholder.com/640x480.png/000099?text=ullam + https://via.placeholder.com/640x480.png/003399?text=alias + https://via.placeholder.com/640x480.png/009999?text=aut + GD-+/ADU|]W + 0 + male - https://example.com/products/earum-voluptatem-magnam-error-molestiae-odit-consectetur - GD-+5T19 - alias veritatis dignissimos omnis - Sint qui voluptatem quos et. Sint natus beatae ipsum maiores ipsa quas. + https://example.com/products/deleniti-rerum-ratione-voluptas-ut-explicabo-ad-provident + GD-0TMMSV" + illum sint minima consequatur + Voluptate sed rerum rerum optio asperiores ipsam consequatur. Neque maxime et voluptatibus at id. Sequi praesentium eum dolores non itaque. Eos et ullam veniam ipsam et delectus. true - 553 + 756 RUR - consequatur - https://via.placeholder.com/640x480.png/00bb99?text=voluptas - https://via.placeholder.com/640x480.png/00bb22?text=recusandae - https://via.placeholder.com/640x480.png/0088ee?text=fugit - GD-+5T19 - 9 - male + nostrum + https://via.placeholder.com/640x480.png/005511?text=ipsum + https://via.placeholder.com/640x480.png/001188?text=cumque + https://via.placeholder.com/640x480.png/007777?text=omnis + GD-0TMMSV" + 6 + female diff --git a/docs/topics/advanced-usage.topic b/docs/topics/advanced-usage.topic deleted file mode 100644 index e05a780..0000000 --- a/docs/topics/advanced-usage.topic +++ /dev/null @@ -1,267 +0,0 @@ - - - - - Extended use of %instance% - Extended use of %instance% - Extended use of %instance% - - - - - -
    • -
    • -
    • -
    • -
    • -     - -

    - The use of directives is available only when generating feeds in the XML format. -

    -     - - - - - - - -

    - By default, the name of the root element is derived from the base name of the feed class. -

    - -

    - For example, for the App\Feeds\FooBarFeed class, the name is foo_bar. -

    -     - -

    - To add a root element and/or its attributes, override the root method: -

    - - - -

    - To disable the addition of the root element, specify its name as empty — null or - "". -

    - -

    - This code will result in: -

    - - -     - - - - - - -

    - To add information to the beginning of the root element (if present) or without it, - override the - info method in the feed class and create an object that extends the - DragonCode\LaravelFeed\Feeds\Info\FeedInfo class: -

    - - - - -

    - This code will result in: -

    - - - -

    - If you need to change the order in which the root element is output relative to the - information block, set the beforeInfo parameter in the root method: -

    - - - -

    - This code will result in: -

    - - -     - - - - - -

    - To change the header and footer, override the header and footer methods: -

    - - - -

    - This code will result in: -

    - - -     - - - - - - - -

    - This code will result in: -

    - - -     -     - - - - - - Indicates an array of attributes - -

    - You can use a key named @attributes to add attributes to a node: -

    - - - - - -

    - This code will result in: -

    - - -     - - - - - Indicates the applicable value "as it is" - - - Note that the value of the @value field must be a string. - - -

    - You can use a key named @value to add value to a node: -

    - - - -

    - This code will result in: -

    - - -     - - - - - Allows the use of XML markup without transformation - - - It is also possible to wrap the value of a node into a CDATA section. - This allows you to use reserved characters. - - -

    - You can use a key named @cdata to add CDATA to a node: -

    - - - -

    - This code will result in: -

    - - -     - - - - - Allows you to use XML markup directly within the structure of the document - -

    - To insert XML fragments “as is”, use the @mixed directive: -

    - - - -

    - This code will result in: -

    - - -     - - - - - Describes the possibility of listing an array of elements with the same keys - -

    - In some cases, you need to place an array of elements with the same names. -

    - -

    - To do this, add a @ symbol to the start of the key name: -

    - - - -

    - This code will result in: -

    - - -     -     - - -

    - By default, feeds are stored in public storage, - and the file name will be automatically generated from the feed class name after - App\Feeds\ in kebab-case format. - For example: -

    - - - # App\Feeds\UserFeed - user-feed.xml - - # App\Feeds\Sitemaps\ProductFeed - sitemaps-product-feed.xml - - -

    - You can change these values by overriding the $storage property and the - filename method: -

    - - -     - - -

    - Database queries use chunks, which are 1000 items by default. - You can change this by overriding the chunkSize method: -

    - - -     -     diff --git a/docs/topics/create-feeds.topic b/docs/topics/create-feeds.topic index 7140042..e18d7e5 100644 --- a/docs/topics/create-feeds.topic +++ b/docs/topics/create-feeds.topic @@ -110,7 +110,7 @@ You can generate feeds in different formats. A feed class can be correctly exported only to the format for which it is intended. This is due to the use of - directives and other format specifics. + directives and other format specifics.

    diff --git a/docs/topics/directives.topic b/docs/topics/directives.topic new file mode 100644 index 0000000..5ee0f1f --- /dev/null +++ b/docs/topics/directives.topic @@ -0,0 +1,133 @@ + + + + + Instructions for creating and populating the feed, feed item, and feed info classes + Instructions for creating and populating the feed, feed item, and feed info classes + Instructions for creating and populating the feed, feed item, and feed info classes + + + + + +

    • +
    • +
    • +
    • +
    • + + +

    + The use of directives is available only when generating feeds in the XML format. +

    + + + + + + Indicates an array of attributes + +

    + You can use a key named @attributes to add attributes to a node: +

    + + + + + +

    + This code will result in: +

    + + +     + + + + + Indicates the applicable value "as it is" + + + Note that the value of the @value field must be a string. + + +

    + You can use a key named @value to add value to a node: +

    + + + +

    + This code will result in: +

    + + +     + + + + + Allows the use of XML markup without transformation + + + It is also possible to wrap the value of a node into a CDATA section. + This allows you to use reserved characters. + + +

    + You can use a key named @cdata to add CDATA to a node: +

    + + + +

    + This code will result in: +

    + + +     + + + + + Allows you to use XML markup directly within the structure of the document + +

    + To insert XML fragments “as is”, use the @mixed directive: +

    + + + +

    + This code will result in: +

    + + +     + + + + + Describes the possibility of listing an array of elements with the same keys + +

    + In some cases, you need to place an array of elements with the same names. +

    + +

    + To do this, add a @ symbol to the start of the key name: +

    + + + +

    + This code will result in: +

    + + +     + diff --git a/docs/topics/elements.topic b/docs/topics/elements.topic new file mode 100644 index 0000000..812d684 --- /dev/null +++ b/docs/topics/elements.topic @@ -0,0 +1,111 @@ + + + + + Extended use of %instance% + Extended use of %instance% + Extended use of %instance% + + + + + + + + +

    + By default, the name of the root element is derived from the base name of the feed class. +

    + +

    + For example, for the App\Feeds\FooBarFeed class, the name is foo_bar. +

    +     + +

    + To add a root element and/or its attributes, override the root method: +

    + + + +

    + To disable the addition of the root element, specify its name as empty — null or + "". +

    + +

    + This code will result in: +

    + + +     + + + + + + +

    + To add information to the beginning of the root element (if present) or without it, + override the + info method in the feed class and create an object that extends the + DragonCode\LaravelFeed\Feeds\Info\FeedInfo class: +

    + + + + +

    + This code will result in: +

    + + + +

    + If you need to change the order in which the root element is output relative to the + information block, set the beforeInfo parameter in the root method: +

    + + + +

    + This code will result in: +

    + + +     + + + + + +

    + To change the header and footer, override the header and footer methods: +

    + + + +

    + This code will result in: +

    + + +     + + + + + + + +

    + This code will result in: +

    + + +     +     diff --git a/docs/topics/eloquent.topic b/docs/topics/eloquent.topic new file mode 100644 index 0000000..c9a2aa2 --- /dev/null +++ b/docs/topics/eloquent.topic @@ -0,0 +1,23 @@ + + + + + Extended use of %instance% + Extended use of %instance% + Extended use of %instance% + + + + +

    + Database queries use chunks, which are 1000 items by default. + You can change this by overriding the chunkSize method: +

    + + +     +     diff --git a/docs/topics/introduction.topic b/docs/topics/introduction.topic index e23d6b5..e800771 100644 --- a/docs/topics/introduction.topic +++ b/docs/topics/introduction.topic @@ -4,7 +4,11 @@ + title="Getting started" id="introduction"> + + Extended use of %instance% + Extended use of %instance% + Extended use of %instance% 📃 %instance% @@ -23,7 +27,7 @@ Usage     - + diff --git a/docs/topics/location.topic b/docs/topics/location.topic new file mode 100644 index 0000000..2806c51 --- /dev/null +++ b/docs/topics/location.topic @@ -0,0 +1,36 @@ + + + + + Extended use of %instance% + Extended use of %instance% + Extended use of %instance% + + + +

    + By default, feeds are stored in public storage, + and the file name will be automatically generated from the feed class name after + App\Feeds\ in kebab-case format. + For example: +

    + + + # App\Feeds\UserFeed + user-feed.xml + + # App\Feeds\Sitemaps\ProductFeed + sitemaps-product-feed.xml + + +

    + You can change these values by overriding the $storage property and the + filename method: +

    + + +     From 62a5731f19ce9ae3b3f982a6a385ec6f40225c4b Mon Sep 17 00:00:00 2001 From: Andrey Helldar Date: Sat, 6 Sep 2025 02:46:47 +0300 Subject: [PATCH 2/2] Updated summaries in documentation topics for clarity and consistency --- docs/topics/directives.topic | 6 +++--- docs/topics/elements.topic | 6 +++--- docs/topics/eloquent.topic | 6 +++--- docs/topics/introduction.topic | 6 +++--- docs/topics/location.topic | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/topics/directives.topic b/docs/topics/directives.topic index 5ee0f1f..c50fb22 100644 --- a/docs/topics/directives.topic +++ b/docs/topics/directives.topic @@ -6,9 +6,9 @@ xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd" title="Directives" id="directives"> - Instructions for creating and populating the feed, feed item, and feed info classes - Instructions for creating and populating the feed, feed item, and feed info classes - Instructions for creating and populating the feed, feed item, and feed info classes + Built-in XML directives for feed output + Built-in XML directives for feed output + Built-in XML directives for feed output diff --git a/docs/topics/elements.topic b/docs/topics/elements.topic index 812d684..b25ea0f 100644 --- a/docs/topics/elements.topic +++ b/docs/topics/elements.topic @@ -6,9 +6,9 @@ xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd" title="Elements" id="elements" help-id="elements"> - Extended use of %instance% - Extended use of %instance% - Extended use of %instance% + Configure feed structure: root element, info block, headers/footers, and attributes + Configure feed structure: root element, info block, headers/footers, and attributes + Configure feed structure: root element, info block, headers/footers, and attributes diff --git a/docs/topics/eloquent.topic b/docs/topics/eloquent.topic index c9a2aa2..9493dcf 100644 --- a/docs/topics/eloquent.topic +++ b/docs/topics/eloquent.topic @@ -6,9 +6,9 @@ xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd" title="Eloquent" id="eloquent"> - Extended use of %instance% - Extended use of %instance% - Extended use of %instance% + Advanced Eloquent settings for feed generation (e.g., chunk size) + Advanced Eloquent settings for feed generation (e.g., chunk size) + Advanced Eloquent settings for feed generation (e.g., chunk size) diff --git a/docs/topics/introduction.topic b/docs/topics/introduction.topic index e800771..1f5217e 100644 --- a/docs/topics/introduction.topic +++ b/docs/topics/introduction.topic @@ -6,9 +6,9 @@ xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd" title="Getting started" id="introduction"> - Extended use of %instance% - Extended use of %instance% - Extended use of %instance% + Overview of %instance% with quick links to installation and usage + Overview of %instance% with quick links to installation and usage + Overview of %instance% with quick links to installation and usage 📃 %instance% diff --git a/docs/topics/location.topic b/docs/topics/location.topic index 2806c51..c810c79 100644 --- a/docs/topics/location.topic +++ b/docs/topics/location.topic @@ -6,9 +6,9 @@ xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd" title="Location" id="location"> - Extended use of %instance% - Extended use of %instance% - Extended use of %instance% + Configure storage disk and output filename for generated feeds + Configure storage disk and output filename for generated feeds + Configure storage disk and output filename for generated feeds