From 7befd9af043386158ef9080723eb18e03f0625c7 Mon Sep 17 00:00:00 2001
From: Jim Winstead <jimw@trainedmonkey.com>
Date: Mon, 25 Nov 2024 12:51:59 -0800
Subject: [PATCH] Add information about Composer and example of using its
 autoloader (#3677)

Co-authored-by: Theodore Brown <theodorejb@outlook.com>
---
 install/composer.xml       | 49 ++++++++++++++++++++++++++++++++++++++
 language/oop5/autoload.xml | 20 ++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 install/composer.xml

diff --git a/install/composer.xml b/install/composer.xml
new file mode 100644
index 000000000000..dcb953436ecf
--- /dev/null
+++ b/install/composer.xml
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<chapter xml:id="install.composer" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Installation of Composer and third-party packages</title>
+
+ <sect1 xml:id="install.composer.intro">
+  <title>Introduction to Composer</title>
+  <simpara>
+   &link.composer; is a dependency manager for PHP that makes it possible
+   to define third-party code packages used by a project that can
+   then be easily installed and updated. It leverages the built-in
+   <link linkend="language.oop5.autoload">class autoloading features</link>
+   of PHP, repositories of PHP packages such as
+   <link xlink:href="&url.packagist;">Packagist</link>, and common project
+   layout and coding conventions.
+  </simpara>
+  <simpara>
+   For example, if a PHP application or website needs
+   to work with <abbrev>UUID</abbrev> values,
+   <link xlink:href="&url.packagist.package;ramsey/uuid">Ben Ramsey's
+   <literal>ramsey/uuid</literal> package</link> that implements the
+   widely known and used types of UUIDs that are defined by
+   <link xlink:href="&url.rfc;4122">RFC 4122</link> could be used.
+  </simpara>
+  <simpara>
+   Briefly, this is done by creating a <literal>composer.json</literal>
+   in the project, using Composer to install the latest version of the
+   package, and including Composer's autoload script to make it available
+   to the code. The <link xlink:href="&url.composer;/doc/01-basic-usage.md">Composer
+   "Basic Usage" documentation</link> goes into this in more depth.
+  </simpara>
+  <example>
+   <title>
+    <literal>composer.json</literal> that requires a single package
+   </title>
+   <programlisting role="javascript">
+<![CDATA[
+{
+    "require": {
+        "ramsey/uuid": "^4.7"
+    }
+}
+]]>
+   </programlisting>
+  </example>
+
+ </sect1>
+</chapter>
diff --git a/language/oop5/autoload.xml b/language/oop5/autoload.xml
index 91f8b902f0aa..41c4d6a9211a 100644
--- a/language/oop5/autoload.xml
+++ b/language/oop5/autoload.xml
@@ -79,6 +79,26 @@ string(5) "ITest"
 Fatal error: Interface 'ITest' not found in ...
 */
 ?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title>Using Composer's autoloader</title>
+    <simpara>
+     &link.composer; generates a <literal>vendor/autoload.php</literal>
+     which is set up to automatically load packages that are being managed
+     by Composer. By including this file, those packages can be used without
+     any additional work.
+    </simpara>
+    <programlisting role="php">
+<![CDATA[
+<?php
+require __DIR__ . '/vendor/autoload.php';
+
+$uuid = new Ramsey\Uuid\Uuid::uuid7();
+
+echo "Generated new UUID -> ", $uuid->toString(), "\n";
+?>
 ]]>
     </programlisting>
    </example>