From 3a478fd5e1d1aafce2e8ebdc18a7d117962e8d5f Mon Sep 17 00:00:00 2001 From: Matt Friedman Date: Fri, 13 Dec 2024 09:03:54 -0800 Subject: [PATCH] Extension Doc - Implementing Filesystem Changes to phpBB --- development/extensions/tutorial_advanced.rst | 169 +++++++++++++++++++ 1 file changed, 169 insertions(+) diff --git a/development/extensions/tutorial_advanced.rst b/development/extensions/tutorial_advanced.rst index 3e21a8a7..919e5fb1 100644 --- a/development/extensions/tutorial_advanced.rst +++ b/development/extensions/tutorial_advanced.rst @@ -16,6 +16,7 @@ This tutorial explains: * `Using service decoration`_ * `Replacing the phpBB Datetime class`_ * `Extension version checking`_ +* `Implementing Filesystem Changes to phpBB`_ Adding a PHP event to your extension ==================================== @@ -526,3 +527,171 @@ branch can be used to provide links to versions in development. ``download`` | "(Optional) A URL to download this version of the extension." ``eol`` | "This is currently not being used yet. Use ``null``" ``security`` | "This is currently not being used yet. Use ``false``" + +Implementing Filesystem Changes to phpBB +======================================== +In certain scenarios, an extension may need to implement filesystem changes within phpBB beyond the extension's +self-contained structure. While this approach is generally discouraged, there are specific conditions where it +may be appropriate. Extensions can safely add or remove files and folders within phpBB’s ``files``, ``images``, +and ``store`` directories, as these are designed to hold user-generated content and are typically not replaced +during phpBB or extension updates. + +There are two primary methods for implementing filesystem changes in phpBB through an extension: + + 1. Using Migrations + 2. Using the Extension Enabling Process (ext.php) + +Below are examples of how to create a directory named ``my_extension_dir`` in the ``store`` directory for storing additional extension-related files. + +Using Migrations +---------------- +While migrations are generally designed for database changes, they offer specific advantages when managing filesystem changes: + + - Existence Check: Use the ``effectively_installed`` method to check if the directory already exists. + - Installation Order: Use the ``depends_on`` method to ensure the directory is created at the correct stage during the extension’s installation process. + - Run separate (optional) filesystem processes during installation and uninstallation. + +.. code-block:: php + + container->get('filesystem'); + protected $my_new_dir = $this->container->getParameter('core.root_path') . 'store/my_extension_dir'; + + public function effectively_installed() + { + return $this->filesystem->exists($this->$my_new_dir); + } + + public static function depends_on() + { + return ['\acme\demo\migrations\first_migration']; + } + + public function update_data(): array + { + return [ + ['custom', [[$this, 'add_dir']]], + ]; + } + + public function revert_data(): array + { + return [ + ['custom', [[$this, 'remove_dir']]], + ]; + } + + public function add_dir() + { + try + { + // Create directory with secure permissions, and add an empty index.htm + if (!$this->filesystem->exists($this->$my_new_dir)) + { + $this->filesystem->mkdir($this->$my_new_dir, 0755); + $this->filesystem->touch($this->$my_new_dir . '/index.htm'); + } + } + catch (\phpbb\filesystem\exception\filesystem_exception $e) + { + // log or handle any errors here using $e->get_filename() or $e->getMessage() + } + } + + public function remove_dir() + { + try + { + if ($this->filesystem->exists($this->$my_new_dir)) + { + $this->filesystem->remove($this->$my_new_dir); + } + } + catch (\phpbb\filesystem\exception\filesystem_exception $e) + { + // log or handle any errors here using $e->get_filename() or $e->getMessage() + } + } + } + +Using ext.php +------------- +Filesystem changes can also be implemented within the extension’s ``ext.php`` file. This method is preferable if: + + - The changes have no specific requirements or dependencies that need monitoring through a migration step. + - The changes should occur at a particular stage, such as enabling, disabling, or deleting the extension. + +.. code-block:: php + + container->get('filesystem'); + $new_dir_path = $this->container->getParameter('core.root_path') . 'store/my_extension_dir'; + + try + { + // Create directory with secure permissions, and add an empty index.htm + if (!$filesystem->exists($new_dir_path)) + { + $filesystem->mkdir($new_dir_path, 0755); + $filesystem->touch($new_dir_path . '/index.htm'); + } + } + catch (\phpbb\filesystem\exception\filesystem_exception $e) + { + // log or handle any errors here using $e->get_filename() or $e->getMessage() + } + + return 'added my_extension_dir'; + } + + return parent::enable_step($old_state); + } + + /** + * Delete a directory from phpBB's store folder + */ + public function purge_step($old_state) + { + if ($old_state === false) + { + $filesystem = $this->container->get('filesystem'); + $new_dir_path = $this->container->getParameter('core.root_path') . 'store/my_extension_dir'; + + try + { + if ($filesystem->exists($new_dir_path)) + { + $filesystem->remove($new_dir_path); + } + } + catch (\phpbb\filesystem\exception\filesystem_exception $e) + { + // log or handle any errors here using $e->get_filename() or $e->getMessage() + } + + return 'removed my_extension_dir'; + } + + return parent::purge_step($old_state); + } + } + +By leveraging one of these methods, you can implement necessary filesystem changes while maintaining compatibility +with phpBB’s structure and best practices.