Download the PHP package spatie/php-structure-discoverer without Composer
On this page you can find all versions of the php package spatie/php-structure-discoverer. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download spatie/php-structure-discoverer
More information about spatie/php-structure-discoverer
Files in spatie/php-structure-discoverer
Package php-structure-discoverer
Short Description Automatically discover structures within your PHP application
License MIT
Homepage https://github.com/spatie/php-structure-discoverer
Informations about the package php-structure-discoverer
Automatically discover classes, interfaces, enums, and traits within your PHP application
With this package, you'll be able to discover structures in your PHP application that fulfill certain conditions quickly. For example, you could search for classes implementing an interface:
As an added benefit, it has a built-in cache functionality that makes the whole process fast in production.
The package is not only limited to classes but can also find enums, interfaces, and traits and has extra metadata for each structure.
Support us
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Installation
You can install the package via composer:
If you're using Laravel, then you can also publish the config file with the following command:
This is the contents of the published config file:
Usage
You always need to define in which directories you want to look for structures:
It is possible to look in multiple directories like this:
You can get the structures as such:
Which will return an array of class FCQN, and because no conditions were added, the package will return all classes, enums, interfaces, and traits.
You only discover classes like this:
Interfaces like this:
Enums like this:
And traits like this:
When you want to include a specific named structure, you can do the following:
You can discover classes extending another class as such:
Discovering classes, interfaces, or enums implementing an interface can be done like this:
Be aware that although interfaces extend another interface, in this context, the implements keyword seemed a more logical choice to find interfaces extended by another interface. Using the extends
method for such a filter won't work!
Classes, interfaces, or traits using an attribute can be discovered as such:
For more fine-grained control, you can use a closure that receives a DiscoveredStructure
object (more on that later) and should return true
if the structure should be included:
More complex custom conditions can be embedded in a class:
This condition can now be used like this:
Combining conditions
By default, all conditions will work like an AND operation, so in this case:
The package will only look for structures that are a class and implement Arrayble
.
You can create an OR combination of conditions like this:
Now, the package will only discover classes or enum structures.
You can also create more complex operations like an or of and's:
This example can be written shorter like this:
Sorting
By default, the discovered structures will be sorted according to the OS' default.
You can change the sorting like this:
Here are all the available sorting options:
Caching
This package can cache all discovered structures, so no performance-heavy operations are required in production.
The fastest way to start caching is by creating a structure scout, which is a class that describes what you want to discover:
Each structure scout extends from StructureScout
and should have
- a definition where you describe what to discover and where. Just like we did inline earlier
- a driver to be used for the cache. When you're using Laravel, this method is not required since it is already defined in the config file
Within your application, you can use the discoverer as such:
The first time this method is called, the whole discovery process will run taking a bit more time. The second call will skip the discovery process and use the cached version, making a call to this method amazingly fast!
In production
When you're deploying to production, you can warm all your structure scout caches as such:
You should provide a directory where the structure scouts are stored.
If you're using Laravel, you can run the following command:``
`
It is also possible to clear all caches for structure scouts as such:
Or, if you're using Laravel:
`
For packages
Since an individual user defines the directories where structure scouts can be found, packages can't ensure their structure scouts will be discovered with the cache commands.
It is possible to add structure scouts like this manually:
In a Laravel application, you typically do this within the package ServiceProvider.
Cache drivers
File
The FileDiscoverCacheDriver
allows you to cache discovered structures in a file. You should provide a directory
parameter where all the cache files should be stored.
Laravel
The LaravelDiscoverCacheDriver
will use the default Laravel cache. You can provide an optional store
parameter to define the store to be used and an optional prefix
parameter for the cache key.
Null
The NullDiscoverCacheDriver
will not cache anything and can be used for testing purposes.
Your own
A cache driver can be built by extending the DiscoverCacheDriver
interface:
Without structure scouts
You can also use caching inline without the use of scouts, be aware warming up these caches in production is not possible:
Parallel
Getting all structures in a bigger application can be slow due to many files being scanned. This process can be sped up by parallelized scanning. You can enable this as such:
It is possible to set the number of files each process will scan:
By default, each process will scan 50 files.
Chains
Often structures inherit other structures with extends and implementations. The package automatically includes these structures when discovering them. So for example
When using:
Both FormRequest
and UserFormRequest
will be found, and although UserFormRequest
is not a direct descendant of Request
, it is one through FormRequest
.
You can disable this behavior for extending as such:
Or for implementing as such:
Resolving chains is a complicated and resource-heavy process. It can be completely disabled as such:
Full information
The output will be a reference string to the structure when discovering structures. Internally the package keeps track of a lot more information which can be helpful for all purposes. You can also retrieve this information as such:
Instead of returning an array of strings, now an array of DiscoveredStructure
objects is returned. Let's go through the different types:
DiscoveredClass
Represents a class, the $extends
and $implements
properties address the direct extend and implements of the class. The $extendsChain
and $implementsChain
properties contain all extends and implements for the complete inheritance chain.
DiscoveredInterface
Represents a class, the $extends
property addresses the direct extends of the interface. The $extendsChain
property contains all extends for the whole inheritance chain.
DiscoveredEnum
Represents an enum, the $implements
property addresses the direct extends of the enum. The $implementsChain
property contains all implements for the full inheritance chain. The $type
property is an enum describing the type: Unit
, String
, and Int
.
DiscoveredTrait
Represents a discovered trait within the application.
Parsers
The parser is responsible for parsing a file and returning a list of structures. The package comes with two parsers out of the box:
PhpTokenStructureParser
: Reads a PHP file, tokenizes it, and parses the tokens into structures.ReflectionStructureParser
: Uses the PHP reflection API to read a file and parse it into structures.
By default, the PhpTokenStructureParser
is used due to it being more robust, the ReflectionStructureParser
is quite a bit faster but can completely fail the PHP process.
You can enable the ReflectionStructureParser
as such:
You'll likely need to set the basePath to the root of your project, and optionally the root namespace of your project which will be prepended.
For default Laravel projects this would be:
Help? My structure cannot be found!
The internals of this package will scan all files within a directory and try to make a virtual map linking all structures with their extends, uses, and implementations.
Due to this file scanning, this map is incomplete if referenced structures are not being scanned.
For example, we scan for all classes extending Laravel's Model
in our app directory, a lot of models have been found, but the User
model is missing.
The reason why this is happening is that:
- The package searches in the app directory for classes extending
Model
User
extendsAuthenticatable
, which itself extendsModel
Authenticatable
is stored within thevendor/laravel/...
directory, which isn't being scanned- The package does not know that
Authenticatable
extendsModel
User
will not be found
A solution to this problem is to include the laravel
directory in the scanning process.
Testing
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
- Ruben Van Assche
- Construct Finder a big influence for this package
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of php-structure-discoverer with dependencies
amphp/amp Version ^v3.0
amphp/parallel Version ^2.2
illuminate/collections Version ^10.0|^11.0
spatie/laravel-package-tools Version ^1.4.3
symfony/finder Version ^6.0|^7.0