[FEATURE] Delegate URL Handling to UrlGenerators

Author: linawolf

.ddev/config.yaml

@@ -0,0 +1,254 @@
+name: guides
+type: php
+docroot: output
+php_version: "8.1"
+webserver_type: nginx-fpm
+router_http_port: "80"
+router_https_port: "443"
+xdebug_enabled: false
+additional_hostnames: []
+additional_fqdns: []
+nfs_mount_enabled: false
+mutagen_enabled: false
+use_dns_when_possible: true
+composer_version: "2"
+web_environment: []
+nodejs_version: "16"
+omit_containers: [db, ddev-ssh-agent]
+
+# Key features of ddev's config.yaml:
+
+# name: <projectname> # Name of the project, automatically provides
+#   http://projectname.ddev.site and https://projectname.ddev.site
+
+# type: <projecttype>  # drupal6/7/8, backdrop, typo3, wordpress, php
+
+# docroot: <relative_path> # Relative path to the directory containing index.php.
+
+# php_version: "7.4"  # PHP version to use, "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1"
+
+# You can explicitly specify the webimage but this
+# is not recommended, as the images are often closely tied to ddev's' behavior,
+# so this can break upgrades.
+
+# webimage: <docker_image>  # nginx/php docker image.
+
+# database:
+#   type: <dbtype> # mysql, mariadb
+#   version: <version> # database version, like "10.3" or "8.0"
+# Note that mariadb_version or mysql_version from v1.18 and earlier
+# will automatically be converted to this notation with just a "ddev config --auto"
+
+# router_http_port: <port>  # Port to be used for http (defaults to port 80)
+# router_https_port: <port> # Port for https (defaults to 443)
+
+# xdebug_enabled: false  # Set to true to enable xdebug and "ddev start" or "ddev restart"
+# Note that for most people the commands
+# "ddev xdebug" to enable xdebug and "ddev xdebug off" to disable it work better,
+# as leaving xdebug enabled all the time is a big performance hit.
+
+# xhprof_enabled: false  # Set to true to enable xhprof and "ddev start" or "ddev restart"
+# Note that for most people the commands
+# "ddev xhprof" to enable xhprof and "ddev xhprof off" to disable it work better,
+# as leaving xhprof enabled all the time is a big performance hit.
+
+# webserver_type: nginx-fpm  # or apache-fpm
+
+# timezone: Europe/Berlin
+# This is the timezone used in the containers and by PHP;
+# it can be set to any valid timezone,
+# see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+# For example Europe/Dublin or MST7MDT
+
+# composer_root: <relative_path>
+# Relative path to the composer root directory from the project root. This is
+# the directory which contains the composer.json and where all Composer related
+# commands are executed.
+
+# composer_version: "2"
+# You can set it to "" or "2" (default) for Composer v2 or "1" for Composer v1
+# to use the latest major version available at the time your container is built.
+# It is also possible to select a minor version for example "2.2" which will
+# install the latest release of that branch. Alternatively, an explicit Composer
+# version may be specified, for example "1.0.22". Finally, it is also possible
+# to use one of the key words "stable", "preview" or "snapshot" see Composer
+# documentation.
+# To reinstall Composer after the image was built, run "ddev debug refresh".
+
+# nodejs_version: "16"
+# change from the default system Node.js version to another supported version, like 12, 14, 17, 18.
+# Note that you can use 'ddev nvm' or nvm inside the web container to provide nearly any
+# Node.js version, including v6, etc.
+
+# additional_hostnames:
+#  - somename
+#  - someothername
+# would provide http and https URLs for "somename.ddev.site"
+# and "someothername.ddev.site".
+
+# additional_fqdns:
+#  - example.com
+#  - sub1.example.com
+# would provide http and https URLs for "example.com" and "sub1.example.com"
+# Please take care with this because it can cause great confusion.
+
+# upload_dir: custom/upload/dir
+# would set the destination path for ddev import-files to <docroot>/custom/upload/dir
+# When mutagen is enabled this path is bind-mounted so that all the files
+# in the upload_dir don't have to be synced into mutagen
+
+# working_dir:
+#   web: /var/www/html
+#   db: /home
+# would set the default working directory for the web and db services.
+# These values specify the destination directory for ddev ssh and the
+# directory in which commands passed into ddev exec are run.
+
+# omit_containers: [db, dba, ddev-ssh-agent]
+# Currently only these containers are supported. Some containers can also be
+# omitted globally in the ~/.ddev/global_config.yaml. Note that if you omit
+# the "db" container, several standard features of ddev that access the
+# database container will be unusable. In the global configuration it is also
+# possible to omit ddev-router, but not here.
+
+# nfs_mount_enabled: false
+# Great performance improvement but requires host configuration first.
+# See https://ddev.readthedocs.io/en/stable/users/performance/#using-nfs-to-mount-the-project-into-the-container
+
+# mutagen_enabled: false
+# Performance improvement using mutagen asynchronous updates.
+# See https://ddev.readthedocs.io/en/latest/users/performance/#using-mutagen
+
+# fail_on_hook_fail: False
+# Decide whether 'ddev start' should be interrupted by a failing hook
+
+# host_https_port: "59002"
+# The host port binding for https can be explicitly specified. It is
+# dynamic unless otherwise specified.
+# This is not used by most people, most people use the *router* instead
+# of the localhost port.
+
+# host_webserver_port: "59001"
+# The host port binding for the ddev-webserver can be explicitly specified. It is
+# dynamic unless otherwise specified.
+# This is not used by most people, most people use the *router* instead
+# of the localhost port.
+
+# host_db_port: "59002"
+# The host port binding for the ddev-dbserver can be explicitly specified. It is dynamic
+# unless explicitly specified.
+
+# phpmyadmin_port: "8036"
+# phpmyadmin_https_port: "8037"
+# The PHPMyAdmin ports can be changed from the default 8036 and 8037
+
+# host_phpmyadmin_port: "8036"
+# The phpmyadmin (dba) port is not normally bound on the host at all, instead being routed
+# through ddev-router, but it can be specified and bound.
+
+# mailhog_port: "8025"
+# mailhog_https_port: "8026"
+# The MailHog ports can be changed from the default 8025 and 8026
+
+# host_mailhog_port: "8025"
+# The mailhog port is not normally bound on the host at all, instead being routed
+# through ddev-router, but it can be bound directly to localhost if specified here.
+
+# webimage_extra_packages: [php7.4-tidy, php-bcmath]
+# Extra Debian packages that are needed in the webimage can be added here
+
+# dbimage_extra_packages: [telnet,netcat]
+# Extra Debian packages that are needed in the dbimage can be added here
+
+# use_dns_when_possible: true
+# If the host has internet access and the domain configured can
+# successfully be looked up, DNS will be used for hostname resolution
+# instead of editing /etc/hosts
+# Defaults to true
+
+# project_tld: ddev.site
+# The top-level domain used for project URLs
+# The default "ddev.site" allows DNS lookup via a wildcard
+# If you prefer you can change this to "ddev.local" to preserve
+# pre-v1.9 behavior.
+
+# ngrok_args: --basic-auth username:pass1234
+# Provide extra flags to the "ngrok http" command, see
+# https://ngrok.com/docs#http or run "ngrok http -h"
+
+# disable_settings_management: false
+# If true, ddev will not create CMS-specific settings files like
+# Drupal's settings.php/settings.ddev.php or TYPO3's AdditionalConfiguration.php
+# In this case the user must provide all such settings.
+
+# You can inject environment variables into the web container with:
+# web_environment:
+# - SOMEENV=somevalue
+# - SOMEOTHERENV=someothervalue
+
+# no_project_mount: false
+# (Experimental) If true, ddev will not mount the project into the web container;
+# the user is responsible for mounting it manually or via a script.
+# This is to enable experimentation with alternate file mounting strategies.
+# For advanced users only!
+
+# bind_all_interfaces: false
+# If true, host ports will be bound on all network interfaces,
+# not just the localhost interface. This means that ports
+# will be available on the local network if the host firewall
+# allows it.
+
+# default_container_timeout: 120
+# The default time that ddev waits for all containers to become ready can be increased from
+# the default 120. This helps in importing huge databases, for example.
+
+#web_extra_exposed_ports:
+#- name: nodejs
+#  container_port: 3000
+#  http_port: 2999
+#  https_port: 3000
+#- name: something
+#  container_port: 4000
+#  https_port: 4000
+#  http_port: 3999
+# Allows a set of extra ports to be exposed via ddev-router
+# The port behavior on the ddev-webserver must be arranged separately, for example
+# using web_extra_daemons.
+# For example, with a web app on port 3000 inside the container, this config would
+# expose that web app on https://<project>.ddev.site:9999 and http://<project>.ddev.site:9998
+# web_extra_exposed_ports:
+#  - container_port: 3000
+#    http_port: 9998
+#    https_port: 9999
+
+#web_extra_daemons:
+#- name: "http-1"
+#  command: "/var/www/html/node_modules/.bin/http-server -p 3000"
+#  directory: /var/www/html
+#- name: "http-2"
+#  command: "/var/www/html/node_modules/.bin/http-server /var/www/html/sub -p 3000"
+#  directory: /var/www/html
+
+# override_config: false
+# By default, config.*.yaml files are *merged* into the configuration
+# But this means that some things can't be overridden
+# For example, if you have 'nfs_mount_enabled: true'' you can't override it with a merge
+# and you can't erase existing hooks or all environment variables.
+# However, with "override_config: true" in a particular config.*.yaml file,
+# 'nfs_mount_enabled: false' can override the existing values, and
+# hooks:
+#   post_start: []
+# or
+# web_environment: []
+# or
+# additional_hostnames: []
+# can have their intended affect. 'override_config' affects only behavior of the
+# config.*.yaml file it exists in.
+
+# Many ddev commands can be extended to run tasks before or after the
+# ddev command is executed, for example "post-start", "post-import-db",
+# "pre-composer", "post-composer"
+# See https://ddev.readthedocs.io/en/stable/users/extend/custom-commands/ for more
+# information on the commands that can be extended and the tasks you can define
+# for them. Example:
+#hooks:

packages/guides-restructured-text/resources/config/guides-restructured-text.php

@@ -4,6 +4,7 @@
 
 use phpDocumentor\Guides\Graphs\Directives\UmlDirective;
 use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Directives\AdmonitionDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\AttentionDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
@@ -105,7 +106,6 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 use phpDocumentor\Guides\RestructuredText\Toc\GlobSearcher;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 
@@ -165,7 +165,7 @@
         ])
         ->set(ContainerDirective::class)
         ->set(ContentsDirective::class)
-        ->arg('$urlGenerator', service(UrlGeneratorInterface::class))
+        ->arg('$documentNameResolver', service(DocumentNameResolverInterface::class))
         ->set(CsvTableDirective::class)
         ->arg('$productions', service('phpdoc.guides.parser.rst.body_elements'))
         ->set(DangerDirective::class)

packages/guides-restructured-text/src/RestructuredText/Directives/ContentsDirective.php

@@ -6,9 +6,9 @@
 
 use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 
 /**
  * Standarad rst `contents` directive
@@ -17,8 +17,9 @@
  */
 class ContentsDirective extends BaseDirective
 {
-    public function __construct(private readonly UrlGeneratorInterface $urlGenerator)
-    {
+    public function __construct(
+        private readonly DocumentNameResolverInterface $documentNameResolver,
+    ) {
     }
 
     public function getName(): string
@@ -32,7 +33,7 @@ public function process(
         Directive $directive,
     ): Node|null {
         $options = $directive->getOptions();
-        $absoluteUrl = $this->urlGenerator->absoluteUrl(
+        $absoluteUrl = $this->documentNameResolver->absoluteUrl(
             $blockContext->getDocumentParserContext()->getContext()->getDirName(),
             $blockContext->getDocumentParserContext()->getContext()->getCurrentFileName(),
         );

packages/guides-restructured-text/src/RestructuredText/Directives/ImageDirective.php

@@ -6,9 +6,9 @@
 
 use phpDocumentor\Guides\Nodes\ImageNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 
 use function dirname;
 
@@ -21,8 +21,9 @@
  */
 class ImageDirective extends BaseDirective
 {
-    public function __construct(private readonly UrlGeneratorInterface $urlGenerator)
-    {
+    public function __construct(
+        private readonly DocumentNameResolverInterface $documentNameResolver,
+    ) {
     }
 
     public function getName(): string
@@ -36,7 +37,7 @@ public function processNode(
         Directive $directive,
     ): Node {
         return new ImageNode(
-            $this->urlGenerator->absoluteUrl(
+            $this->documentNameResolver->absoluteUrl(
                 dirname($blockContext->getDocumentParserContext()->getContext()->getCurrentAbsolutePath()),
                 $directive->getData(),
             ),

packages/guides-restructured-text/src/RestructuredText/Toc/GlobSearcher.php

@@ -6,14 +6,15 @@
 
 use Flyfinder\Specification\Glob;
 use phpDocumentor\Guides\ParserContext;
-use phpDocumentor\Guides\UrlGeneratorInterface;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 
 use function rtrim;
 
 class GlobSearcher
 {
-    public function __construct(private readonly UrlGeneratorInterface $urlGenerator)
-    {
+    public function __construct(
+        private readonly DocumentNameResolverInterface $documentNameResolver,
+    ) {
     }
 
     /** @return string[] */
@@ -25,7 +26,7 @@ public function globSearch(ParserContext $parserContext, string $globPattern): a
         );
         $allFiles = [];
         foreach ($files as $file) {
-            $allFiles[] = $this->urlGenerator->absoluteUrl($parserContext->getDirName(), $file['filename']);
+            $allFiles[] = $this->documentNameResolver->absoluteUrl($parserContext->getDirName(), $file['filename']);
         }
 
         return $allFiles;

packages/guides-restructured-text/tests/unit/Parser/Productions/RuleTestCase.php

@@ -9,13 +9,13 @@
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\ProjectNode;
 use phpDocumentor\Guides\ParserContext;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolver;
 use phpDocumentor\Guides\RestructuredText\MarkupLanguageParser;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineParser;
 use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
-use phpDocumentor\Guides\UrlGenerator;
 use PHPUnit\Framework\TestCase;
 
 abstract class RuleTestCase extends TestCase
@@ -41,7 +41,7 @@ protected function createContext(string $input): BlockContext
             'test',
             1,
             self::createStub(FilesystemInterface::class),
-            new UrlGenerator(),
+            new DocumentNameResolver(),
         );
         $documentParserContext = new DocumentParserContext(
             $parserContext,