refactor: Cleanup git state - commit all staged changes

Major refactoring cleanup:
- Add new controller architecture (class-controller-*.php)
- Add new settings-v2 UI (views/settings-v2/)
- Add new CSS architecture (agentic-sidebar.css, tokens)
- Add esbuild build pipeline (scripts/build.js, package.json)
- Add composer dependencies (vendor/)
- Add frontend src directory (assets/js/src/index.jsx)
- Add documentation files
- Remove old/obsolete files (class-settings.php, old CSS)

This commits all pending changes from previous refactoring efforts.
This commit is contained in:
Dwindi Ramadhana
2026-06-17 05:27:58 +07:00
parent d3f142222c
commit 690991c526
7963 changed files with 941566 additions and 67372 deletions

View File

@@ -0,0 +1,60 @@
Expressions
===========
Starting with version 5.4, we now support parsing expressions and extracting types and references to elements from them.
.. info::
An expression is, for example, the default value for a property or argument, the definition of an enum case or a
constant value. These are called expressions and can contain more complex combinations of operators and values.
As this library revolves around reflecting Static information, most parts of an expression are considered irrelevant;
except for type information -such as type hints- and references to other elements, such as constants. As such, whenever
an expression is interpreted, it will result in a string containing placeholders and an array containing the reflected
parts -such as FQSENs-.
This means that the getters like ``getDefault()`` will return a string or when you provide the optional argument
$isString as being false, it will return an Expression object; which, when cast to string, will provide the same result.
.. warning::
Deprecation: In version 6, we will remove the optional argument and always return an Expression object. When the
result was used as a string nothing will change, but code that checks if the output is a string will no longer
function starting from that version.
This will allow consumers to be able to extract types and links to elements from expressions. This allows consumers to,
for example, interpret the default value for a constructor promoted properties when it directly instantiates an object.
Creating expressions
--------------------
.. hint::
The description below is only for internal usage and to understand how expressions work, this library deals with
this by default.
In this library, we use the ExpressionPrinter to convert a PHP-Parser node -or expression- into an expression
like this::
$printer = new ExpressionPrinter();
$expressionTemplate = $printer->prettyPrintExpr($phpParserNode);
$expression = new Expression($expressionTemplate, $printer->getParts());
In the example above we assume that there is a PHP-Parser node representing an expression; this node is passed to the
ExpressionPrinter -which is an adapted PrettyPrinter from PHP-Parser- which will render the expression as a readable
template string containing placeholders, and a list of parts that can slot into the placeholders.
Consuming expressions
---------------------
When using this library, you can consume these expression objects either by
1. Directly casting them to a string - this will replace all placeholders with the stringified version of the parts
2. Use the render function - this will do the same as the previous methods but you can specify one or more overrides
for the placeholders in the expression
The second method can be used to create your own string values from the given parts and render, for example, links in
these locations.
Another way to use these expressions is to interpret the parts array, and through that way know which elements and
types are referred to in that expression.

View File

@@ -0,0 +1,34 @@
.. _extending:
Extend the library
==================
The model exposed by this library is closed for inheritance. We did this to ensure the model is stable and does not
change via external factors. The complexity of this project makes it hard to keep all the internal classes stable.
The model is designed to be cached and constructed very carefully to ensure performance and memory usage are optimal.
Metadata
--------
Metadata is a way to extend the model with additional information. We call this metadata, as all first class
elements in the reflected codebase are part of the model. Extra data can be added to these elements using metadata.
Elements supporting metadata are:
.. phpdoc:class-list:: [?(@.interfaces contains "\phpDocumentor\Reflection\Metadata\MetaDataContainer")]
.. phpdoc:name::
.. warning::
Adding metadata might break the posibilty to cache the model. Be carefull with circular references and large
objects. We do recommend to keep the metadata small and simple.
Continue reading :doc:`Creating your first metadata <meta-data>`_ to learn how to create your own metadata.
.. toctree::
:maxdepth: 1
:titlesonly:
:hidden:
meta-data

View File

@@ -0,0 +1,77 @@
Metadata
=====
The model of this library is as closed as possible.
Main reason is because consumers of the library should rely on cache.
A mutable and flexible interface of the model would most likely break the caching.
However after some time the users to this library started requesting for a more flexible format.
This is why metadata was introduced.
Create your first metadata
--------------------------
First step is to create your own metadata implementation.
.. code:: php
final class Hook implements \phpDocumentor\Reflection\Metadata\Metadata
{
private string $hook;
public function __construct(string $hook)
{
$this->hook = $hook;
}
public function key(): string
{
return "project-metadata";
}
public function hook(): string
{
return $this->hook;
}
}
.. note::
We do highly recommend to keep your metadata objects small.
When reflecting a large project the number of objects will grow fast.
Now we have an class that can be used it is time to create a :php:class:`\phpDocumentor\Reflection\Php\ProjectFactoryStrategy`.
Strategies are used to reflect nodes in the AST of `phpparser`_.
In the example below we are adding the Hook metadata to any functions containing a function call.
.. code:: php
use \phpDocumentor\Reflection\Php\Function;
final class HookStrategy implements \phpDocumentor\Reflection\Php\ProjectFactoryStrategy
{
public function matches(ContextStack $context, object $object): bool
{
return $this->context->peek() instanceof Function_ &&
$object instanceof \PhpParser\Node\Expr\FuncCall &&
((string)$object->name) === 'hook'
}
public function create(ContextStack $context, object $object, StrategyContainer $strategies): void
{
$method = $context->peek();
$method->addMetadata(new Hook($object->args[0]->value));
}
}
.. note::
To speed up the reflection of your project the default factory instance has a Noop strategy. This strategy will
ignore all statements that are not handled by any strategy. Keep this in mind when implementing your own strategies
especially the statements you are looking for are nested in other statements like a ``while`` loop.
Finally add your new strategy to the project factory.
.. code:: php
$factory = \phpDocumentor\Reflection\Php\ProjectFactory::createInstance();
$factory->addStrategy(new HookStrategy());
.. _phpparser: https://github.com/nikic/PHP-Parser/

View File

@@ -0,0 +1,49 @@
Getting started
===============
This page will give you a quick introduction to the `phpdocumentor/reflection` package and how to get started with it.
Installation
------------
In order to inspect a codebase you need to tell composer to include the `phpdocumentor/reflection` package. This
can easily be done using the following command in your command line terminal:
.. code-block:: bash
composer require phpdocumentor/reflection:~6.0
In order to use the library you need to include the autoloader of composer in your code.
This can be done by adding the following line to your code:
.. code-block:: php
<?php
require_once 'vendor/autoload.php';
After the installation is complete no further configuration is necessary and you can immediately start using it.
Basic usage
------------
The :php:class:`\phpDocumentor\Reflection\Php\ProjectFactory` class is the entry point to the library and is used to create a new
project object that contains all the information about your codebase. It is configured with sensible defaults. And for most
usecases you can just use it as is.
.. code-block:: php
$projectFactory = \phpDocumentor\Reflection\Php\ProjectFactory::createInstance();
At this point we are ready to analyze your complete project or just one file at the time. Just pass an array of file paths to the `create` method of the project factory.
.. code-block:: php
$projectFiles = [new \phpDocumentor\Reflection\File\LocalFile('tests/example.file.php')];
$project = $projectFactory->create('My Project', $projectFiles);
When the process is ready a new object of type :php:class:`phpDocumentor\Reflection\Php\Project` will be returned that
contains a complete hierarchy of all files with their classes, traits and interfaces (and everything in there), but also
all namespaces and packages as a hierarchical tree.
This library does not provide a way to access the structure of the codebase in a searchable way.
This is up to the consumer of the library to implement.

View File

@@ -0,0 +1,29 @@
Reflection
==========
Using this library it is possible to statically reflect one or more files and create an object graph representing
your application's structure, including accompanying in-source documentation using DocBlocks.
The information that this library provides is similar to what the (built-in) Reflection extension of PHP provides; there
are however several advantages to using this library:
- Due to its Static nature it does not execute procedural code in your reflected files where Dynamic Reflection does.
- Because the none of the code is interpreted by PHP (and executed) Static Reflection uses less memory.
- Can reflect complete files
- Can reflect a whole project by reflecting multiple files.
- Reflects the contents of a DocBlock instead of just mentioning there is one.
- Is capable of analyzing code written for any PHP version (starting at 5.2) up to the lastest version, even if your installed
PHP version is lower than the code you are reflecting.
.. note::
As this library focuses on reflecting the structure of the codebase, it does not provide any options to manipulate
the output. If you want to collect more information from the codebase you can read about :ref:`extending the library <extending>`.
.. toctree::
:hidden:
:maxdepth: 2
getting-started
reflection-structure
expressions
extending/index

View File

@@ -0,0 +1,20 @@
Reflection structure
====================
The project created by the :php:class:`\phpDocumentor\Reflection\Php\ProjectFactory` class contains a hierarchy of objects
that represent the structure of your codebase. This hierarchy includes:
Files
Each file is represented by an object of type :php:class:`\phpDocumentor\Reflection\Php\File` which contains
information about the file such as its name, path, and contents. But also the elements that are defined in the file.
Files can be accessed through the :php:method:`\phpDocumentor\Reflection\Php\Project::getFiles()` method of the project object.
Files are a flat list of all files that were analyzed, regardless of their location in the directory structure.
Namespaces
Namespaces are represented by objects of type :php:class:`\phpDocumentor\Reflection\Php\Namespace_`. Each namespace
contains a list of classes, interfaces, traits, and functions that are defined within it. Namespaces can be accessed
through the :php:method:`\phpDocumentor\Reflection\Php\Project::getNamespaces()` method of the project object.
Namespaces are hierarchical and can contain sub-namespaces.
Both namespaces and files do contain the other structural elements that are defined in them, such as classes, interfaces, traits, and functions.
This library does not provide a way to access the structure of the codebase in a searchable way. This is up to the consumer of the library to implement.