Download the PHP package cspray/architectural-decision without Composer
On this page you can find all versions of the php package cspray/architectural-decision. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download cspray/architectural-decision
More information about cspray/architectural-decision
Files in cspray/architectural-decision
Package architectural-decision
Short Description A library to keep track of architectural decisions with PHP annotations.
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package architectural-decision
Architectural Decision
An Architectural Decision is a design decision that could potentially have a large impact on your codebase. Why those decisions were made, from a technical perspective and a business perspective, are important, so they should be documented properly. This library allows you to document Architectural Decision Records (ADR) as an Attribute within your codebase. Doing so provides some functionality that might be useful:
- Architectural Decisions are close to your codebase. As in, the decision is right there in the repo, and you don't have to hunt through another system to find it.
- Architectural Decisions are code in your codebase. As an Attribute you can mark the places in your code that are impacted by this decision. This makes it easier to remember for existing maintainers and easier for new developers to realize there's relevant information. If you implement the ADR following the conventions of this library PHPStorm and other IDEs will show you that decision simply by hovering over the Attribute.
- Statically analyze the impact of your decision. Over time as more of your codebase becomes annotated with Attributes you may be able to glean more information about the decision.
Installation
Requirements
Before using this library there are a couple assumptions that I make, especially when using the provided bin/architectural-decisions CLI tool. If you're using Composer for installing and autoloading the assumptions are pretty safe, but they're worth pointing out.
- There's a
composer.jsonfile present in the root of your project. - That configuration has an
autoloadwith apsr-4orpsr-0entry that specifies 1 or more directories in the root of your project. - Inside the directories specified in your autoloader at least 1 Attribute implementing
ArchitecturalDecisionRecordexists. - All
ArchitecturalDecisionRecordimplementations should be able to be created with no constructor dependencies.
If these assumptions don't hold up for you the bulk of the functionality provided by this library is in the Cspray\ArchitecturalDecision\ArchitecturalDecisionAttributeGatherer and the Cspray\ArchitecturalDecision\XmlDocumentGenerator implementations. It would be fairly straightforward to implement this library with your own assumptions.
Usage Guide
The first thing to do is implement an Architectural Decision Record! This is handled with the Cspray\ArchitecturalDecision\ArchitecturalDecisionRecord interface. I recommend you use the abstract Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision class. This implementation will use the DocBlock for the Attribute as the contents of the decision.
Optionally, you can also annotate appropriate places in your codebase where it might make sense to do so. After that you can run a command to generate an XML document detailing all of your decisions and where they were annotated in your codebase.
If successful a file named architectural-decisions.xml will be generated and stored in the root of your project. You can use this file to generate views into the content, assist in static analysis, or whatever else you might want to do with the ADR information and where it is used in your codebase.
Setting Custom Meta Data
There might be additional information you'd like to include with an ArchitecturalDecisionRecord that doesn't fit into the contents of the decision. Perhaps it is additional data that can be used with static analysis. Perhaps you like to include information about who authored the decision or some other meta-data. You can implement the ArchitecturalDecisionRecord::setMetaData(DOMElement $meta) method to add whatever data you'd like to the generated XML document. Please review the DOMDocument documentation for how to appropriately add elements and attribute to the <meta> element.
Example XML Document
This document was generated by parsing this library. We include a lightweight example for why you should use Attributes for ADR!
