From 586854d29aa377e37b801756178bbc122312e65e Mon Sep 17 00:00:00 2001 From: Andreas Wolf Date: Mon, 8 Apr 2024 22:25:47 +0200 Subject: [PATCH] Add README file --- README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..e8548ee2 --- /dev/null +++ b/README.md @@ -0,0 +1,135 @@ +# Fractor – a generic file refactoring tool + +Fractor is a generic tool for changing all kinds of files via defined rules—similar to what [Rector](https://github.com/rectorphp/rector/) does for PHP. + +## How it works + +The main package `a9f/fractor` provides infrastructure for configuring and running Fractor, +but no rules for changing any files. +These are provided by packages specific for filetypes (like `a9f/fractor-xml`) +or ecosystems (like `a9f/typo3-fractor`). + +For different file types, different operation modes are possible. +For XML, there is a full-blown tree traversal implemented in `a9f/fractor-xml`, +allowing extensions to listen to single nodes in a very similar fashion to Rector. + +In principle, this is also possible for e.g. JSON or YAML files +if they are converted into a tree-like data structure. +Such a structure also provides advantages in keeping formatting intact as much as possible. +However, since PHP does not have strong parsers for these formats that emit an AST for them, +there is no advanced support available right now. + +## Using Fractor + +To utilize Fractor effectively, follow these steps: + +1. **Installation**: + - Install Fractor via Composer by running the following command in your terminal: + ``` + composer require a9f/fractor a9f/fractor-xml + + # if you want to use Fractor with TYPO3, use this instead: + composer require a9f/typo3-fractor + ``` + +2. **Configuration**: + - Create a PHP configuration file (e.g., `fractor.php`) where you define the rules to be applied. + - At minimum, a configuration file must specify the paths to process, the file processor(s) to use and the rule(s) to apply: + ```php + import(__DIR__ . '/vendor/a9f/fractor-xml/config/fractor.php'); + + $config->setPaths([ + __DIR__ . '/output/', + ]); + + $config->withFileProcessor(XmlFileProcessor::class); + + $config->withRule(AddRenderTypeToFlexFormFractor::class); + $config->withRule(DummyRule::class); + }; + ``` + +3. **Running Fractor**: + - Execute Fractor from the command line, passing the path to your configuration file as an argument: + ``` + ./vendor/bin/fractor process -f fractor.php + ``` + +4. **Review Changes**: + - Fractor will apply the rules specified in the configuration file to the targeted files. + - Review the changes made by Fractor to ensure they meet your expectations. + +5. **Customization**: + - You can modify existing rules or create new ones to tailor Fractor's behavior to your specific needs. + - See the "Extending Fractor" section for guidance on creating custom rules. + +## Extending Fractor + +Fractor can be extended with additional transformation rules and support for new file types. + +### Adding Custom Rules + +Here's how you can extend Fractor with a custom rule: + +1. **Creating New Rules**: + - Create a new rule by subclassing the appropriate rule class for the file type, + e.g. `\a9f\FractorXml\XmlFractor` for XML files. + - Each rule should specify the conditions under which it should be applied and the corresponding changes to be made. + - Ideally, new rules also have a test case that validates that they work correctly. + +2. **Registering New Rules**: + - Register your custom rules within the Fractor configuration file. + +### Supporting New File Types + +1. **Supporting New File Types**: + - To support a new file type, you will need to implement an instance of `\a9f\Fractor\Fractor\FileProcessor`. + This processor must take care of decoding a file and then traversing the decoded file structure + (e.g. the DOM tree of an XML file; see `\a9f\FractorXml\XmlFileProcessor` for an example) + +2. **Testing**: + - Thoroughly test your extensions to ensure they function as expected and do not introduce unintended side effects. + - Write unit tests for your custom rules and parsers to maintain code quality and stability. + +3. **Documentation**: + - Document your custom rules and file type extensions to aid other users in understanding and utilizing your contributions. + +By extending Fractor in this manner, you can enhance its capabilities and adapt it to handle a wider range of file formats and transformation scenarios. + +## Contributing + +If you encounter any issues or have suggestions for improvements, +we welcome contributions from the community. Here's how you can contribute: + +1. Fork the repository. +2. Make your changes. +3. Submit a pull request with a clear description of your changes and why they are needed. + +## Support + +For any questions or support regarding Fractor, please open an issue on GitHub. We'll do our best to assist you promptly. + +## License + +Fractor is licensed under the MIT License. + +## Acknowledgments + +Fractor wouldn't be possible without the amazing work of all the open source libraries we rely on. +We're grateful for their contributions to the PHP ecosystem. + +----- + +Thank you for using Fractor to streamline your software update process! +We hope it helps make your development workflow more efficient and enjoyable. +If you have any feedback or suggestions, we'd love to hear from you. + +Happy coding! 🚀 \ No newline at end of file