Skip to content

[v5] Fixed invalid code sample includes #2967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 3 commits into
base: 5.0
Choose a base branch
from
Open

[v5] Fixed invalid code sample includes #2967

wants to merge 3 commits into from
+112 −109

Conversation

@mnocon
Copy link
Contributor

@mnocon mnocon commented Dec 2, 2025 •
edited by adriendupuis
Loading

This PR fixes the wrong file includes in different files of the doc (after I've broken them when upgrading the code to v5).

Preview Reference (4.6)
docs/administration/back_office/back_office_menus/back_office_menus.md docs/administration/back_office/back_office_menus/back_office_menus.md
docs/administration/back_office/back_office_tabs/back_office_tabs.md docs/administration/back_office/back_office_tabs/back_office_tabs.md
docs/administration/back_office/customize_calendar.md docs/administration/back_office/customize_calendar.md
docs/administration/recent_activity/recent_activity.md docs/administration/recent_activity/recent_activity.md
docs/api/php_api/php_api.md docs/api/php_api/php_api.md
docs/content_management/content_api/browsing_content.md docs/content_management/content_api/browsing_content.md
docs/content_management/content_api/creating_content.md docs/content_management/content_api/creating_content.md
docs/content_management/content_management_api/bookmark_api.md docs/content_management/content_management_api/bookmark_api.md
docs/content_management/content_management_api/object_state_api.md docs/content_management/content_management_api/object_state_api.md
docs/content_management/content_management_api/section_api.md docs/content_management/content_management_api/section_api.md
docs/content_management/field_types/create_custom_generic_field_type.md docs/content_management/field_types/create_custom_generic_field_type.md
docs/content_management/taxonomy/taxonomy_api.md docs/content_management/taxonomy/taxonomy_api.md
docs/content_management/url_management/url_api.md docs/content_management/url_management/url_api.md
docs/content_management/workflow/workflow_api.md docs/content_management/workflow/workflow_api.md
docs/pim/product_api.md docs/pim/product_api.md
docs/search/search_api.md docs/search/search_api.md
docs/templating/queries_and_controllers/controllers.md docs/templating/queries_and_controllers/controllers.md
docs/tutorials/generic_field_type/6_settings.md docs/tutorials/generic_field_type/6_settings.md
docs/tutorials/generic_field_type/7_add_a_validation.md docs/tutorials/generic_field_type/7_add_a_validation.md
docs/users/segment_api.md docs/users/segment_api.md

@github-actions
Copy link

github-actions bot commented Dec 2, 2025 •
edited by mnocon
Loading

Preview of modified files

Preview of modified Markdown:

@github-actions
Copy link

github-actions bot commented Dec 2, 2025

code_samples/ change report

Before (on target branch)After (in current PR)

code_samples/api/rest_api/src/Rest/ValueObjectVisitor/Greeting.php

docs/api/rest_api/extending_rest_api/creating_new_rest_resource.md@92:``` php
docs/api/rest_api/extending_rest_api/creating_new_rest_resource.md@93:[[= include_file('code_samples/api/rest_api/src/Rest/ValueObjectVisitor/Greeting.php') =]]
docs/api/rest_api/extending_rest_api/creating_new_rest_resource.md@94:```

001⫶<?php declare(strict_types=1);
002⫶
003⫶namespace App\Rest\ValueObjectVisitor;
004⫶
005⫶use Ibexa\Contracts\Rest\Output\Generator;
006⫶use Ibexa\Contracts\Rest\Output\ValueObjectVisitor;
007⫶use Ibexa\Contracts\Rest\Output\Visitor;
008⫶
009⫶class Greeting extends ValueObjectVisitor
010⫶{
011⫶    /**
012⫶     * @param \App\Rest\Values\Greeting $data
013⫶     */

code_samples/api/rest_api/src/Rest/ValueObjectVisitor/Greeting.php

docs/api/rest_api/extending_rest_api/creating_new_rest_resource.md@92:``` php
docs/api/rest_api/extending_rest_api/creating_new_rest_resource.md@93:[[= include_file('code_samples/api/rest_api/src/Rest/ValueObjectVisitor/Greeting.php') =]]
docs/api/rest_api/extending_rest_api/creating_new_rest_resource.md@94:```

001⫶<?php declare(strict_types=1);
002⫶
003⫶namespace App\Rest\ValueObjectVisitor;
004⫶
005⫶use Ibexa\Contracts\Rest\Output\Generator;
006⫶use Ibexa\Contracts\Rest\Output\ValueObjectVisitor;
007⫶use Ibexa\Contracts\Rest\Output\Visitor;
008⫶
009⫶class Greeting extends ValueObjectVisitor
010⫶{
011⫶    /**
012⫶     * @param \App\Rest\Values\Greeting $data
013⫶     */
014⫶    public function visit(Visitor $visitor, Generator $generator, $data)
014⫶    public function visit(Visitor $visitor, Generator $generator, $data): void
015⫶    {
016⫶        $visitor->setHeader('Content-Type', $generator->getMediaType('Greeting'));
017⫶        $generator->startObjectElement('Greeting');
018⫶        $generator->attribute('href', $this->router->generate('app.rest.greeting'));
019⫶        $generator->valueElement('Salutation', $data->salutation);
020⫶        $generator->valueElement('Recipient', $data->recipient);
021⫶        $generator->valueElement('Sentence', "{$data->salutation} {$data->recipient}");
022⫶        $generator->endObjectElement('Greeting');
023⫶    }
024⫶}


code_samples/back_office/thumbnails/src/Strategy/StaticThumbnailStrategy.php

docs/administration/back_office/back_office_elements/extending_thumbnails.md@44:```php
docs/administration/back_office/back_office_elements/extending_thumbnails.md@45:[[= include_file('code_samples/back_office/thumbnails/src/Strategy/StaticThumbnailStrategy.php') =]]
docs/administration/back_office/back_office_elements/extending_thumbnails.md@46:```

001⫶<?php
002⫶
003⫶declare(strict_types=1);
004⫶
005⫶namespace App\Strategy;
006⫶
007⫶use Ibexa\Contracts\Core\Repository\Strategy\ContentThumbnail\ThumbnailStrategy;
008⫶use Ibexa\Contracts\Core\Repository\Values\Content\Thumbnail;
009⫶use Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo;
010⫶use Ibexa\Contracts\Core\Repository\Values\ContentType\ContentType;
011⫶
012⫶final readonly class StaticThumbnailStrategy implements ThumbnailStrategy
013⫶{
014⫶    public function __construct(private string $staticThumbnail)
015⫶    {
016⫶    }
017⫶
015⫶    {
016⫶        $visitor->setHeader('Content-Type', $generator->getMediaType('Greeting'));
017⫶        $generator->startObjectElement('Greeting');
018⫶        $generator->attribute('href', $this->router->generate('app.rest.greeting'));
019⫶        $generator->valueElement('Salutation', $data->salutation);
020⫶        $generator->valueElement('Recipient', $data->recipient);
021⫶        $generator->valueElement('Sentence', "{$data->salutation} {$data->recipient}");
022⫶        $generator->endObjectElement('Greeting');
023⫶    }
024⫶}


code_samples/back_office/thumbnails/src/Strategy/StaticThumbnailStrategy.php

docs/administration/back_office/back_office_elements/extending_thumbnails.md@44:```php
docs/administration/back_office/back_office_elements/extending_thumbnails.md@45:[[= include_file('code_samples/back_office/thumbnails/src/Strategy/StaticThumbnailStrategy.php') =]]
docs/administration/back_office/back_office_elements/extending_thumbnails.md@46:```

001⫶<?php
002⫶
003⫶declare(strict_types=1);
004⫶
005⫶namespace App\Strategy;
006⫶
007⫶use Ibexa\Contracts\Core\Repository\Strategy\ContentThumbnail\ThumbnailStrategy;
008⫶use Ibexa\Contracts\Core\Repository\Values\Content\Thumbnail;
009⫶use Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo;
010⫶use Ibexa\Contracts\Core\Repository\Values\ContentType\ContentType;
011⫶
012⫶final readonly class StaticThumbnailStrategy implements ThumbnailStrategy
013⫶{
014⫶    public function __construct(private string $staticThumbnail)
015⫶    {
016⫶    }
017⫶
018⫶    public function getThumbnail(ContentType $contentType, array $fields, ?VersionInfo $versionInfo = null): ?Thumbnail
018⫶    public function getThumbnail(ContentType $contentType, array $fields, ?VersionInfo $versionInfo = null): Thumbnail
019⫶    {
020⫶        return new Thumbnail([
021⫶            'resource' => $this->staticThumbnail,
022⫶        ]);
023⫶    }
024⫶}

019⫶    {
020⫶        return new Thumbnail([
021⫶            'resource' => $this->staticThumbnail,
022⫶        ]);
023⫶    }
024⫶}

 Download colorized diff

@mnocon mnocon marked this pull request as ready for review December 3, 2025 09:22
@mnocon mnocon requested a review from a team December 3, 2025 09:22
@ibexa-workflow-automation-1 ibexa-workflow-automation-1 bot requested review from adriendupuis, dabrt and julitafalcondusza and removed request for a team December 3, 2025 09:22
adriendupuis
adriendupuis reviewed Dec 3, 2025
View reviewed changes
Copy link
Contributor

@adriendupuis adriendupuis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few highlight offsets and unneeded new lines.

Few $output->writeln are not really necessary and narrow the example to CLI, but some are really important to fastly illustrate properties and/or looping; could be debated.

docs/administration/back_office/back_office_tabs/back_office_tabs.md
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The #tab-order section is to be fixed too.

https://doc.ibexa.co/en/4.6/administration/back_office/back_office_tabs/back_office_tabs/#tab-order
https://doc.ibexa.co/en/5.0/administration/back_office/back_office_tabs/back_office_tabs/#tab-order doesn't display the getOrder function

[[= include_file('code_samples/back_office/dashboard/article_tab/src/Tab/Dashboard/Everyone/EveryoneArticleTab.php', 37, 41) =]]

docs/api/php_api/php_api.md
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While in this file, I would also fix this weird indent in ## Exception handling section's example

https://ez-systems-developer-documentation--2967.com.readthedocs.build/en/2967/api/php_api/php_api/#exception-handling

docs/content_management/content_api/browsing_content.md
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrong highlight, two much new line feeds, and maybe an unneeded capital (I can't make a nice suggestion for some "deleted lines" reason):


You can also use it to request other content-related value objects from various services:

``` php hl_lines="14"
[[= include_file('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 0, 5) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 21, 23) =]]
// ...

[[= include_file('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 42, 44) =]][[= include_file('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 50, 58) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/ViewContentMetaDataCommand.php', 113, 116) =]]
```

docs/content_management/content_api/creating_content.md
[[= include_file('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 58, 60) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 49, 55) =]]

[[= include_file('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 60, 63) =]]
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The $output->writeln doesn't worth it. It unnecessarily contextualize the example as being in a CLI command.

Suggested change
[[= include_file('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 60, 63) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/TranslateContentCommand.php', 60, 62) =]]

docs/content_management/content_management_api/section_api.md
``` php
[[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 59, 65) =]][[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 72, 76) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 63, 69) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 75, 80) =]]
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Idem, no need for the $output->writeln

Suggested change
[[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 75, 80) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/SectionCommand.php', 77, 80) =]]

docs/search/search_api.md
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While in this file, in ### Combining independent CriteriaI would rename $locationBId for a more distinguishable variable name where B is more visible.

  • new LocationId($locationBId),
  • eventually new LocationId($BLocationId),,
  • or even new LocationId($BId), as we know it's a location ID.

docs/search/search_api.md
Comment on lines +310 to +311
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 4, 6) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 35, 42) =]]
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 4, 6) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 35, 42) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 4, 6) =]]//…
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 35, 42) =]]

docs/templating/queries_and_controllers/controllers.md

``` php
[[= include_file('code_samples/front/embed_content/src/Controller/RelationController.php', 2, 9) =]]
[[= include_file('code_samples/front/embed_content/src/Controller/RelationController.php', 0, 10) =]][[= include_file('code_samples/front/embed_content/src/Controller/RelationController.php', 16, 18) =]][[= include_file('code_samples/front/embed_content/src/Controller/RelationController.php', 37, 40) =]]
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surprising at first but good idea to have what's look like a real complete PHP file! 👍

docs/tutorials/generic_field_type/6_settings.md
Comment on lines +43 to +46
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 7, 9) =]][[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 10, 16) =]]

[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 40, 46) =]]
// ...
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 41, 48) =]]
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two much new lines.

```php
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 0, 4) =]]
// ...
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 7, 9) =]][[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 10, 16) =]]
// ...  
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Type.php', 41, 48) =]]
```

docs/tutorials/generic_field_type/7_add_a_validation.md
Comment on lines 10 to +12
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Value.php', 6, 23) =]]
// ...
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Value.php', 56, 57) =]]
Copy link
Contributor

@adriendupuis adriendupuis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Value.php', 6, 23) =]]
// ...
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Value.php', 56, 57) =]]
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Value.php', 6, 23) =]]// ...
[[= include_file('code_samples/field_types/2dpoint_ft/src/FieldType/Point2D/Value.php', 56, 57) =]]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@adriendupuis adriendupuis adriendupuis left review comments

@dabrt dabrt Awaiting requested review from dabrt

@julitafalcondusza julitafalcondusza Awaiting requested review from julitafalcondusza

Assignees

No one assigned

Labels

Needs DOC review

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mnocon @adriendupuis