Skip to content

Commit b83c7a1

Browse files
committed
Extension Doc - Implementing Filesystem Changes to phpBB
1 parent f55c9d0 commit b83c7a1

File tree

1 file changed

+169
-0
lines changed

1 file changed

+169
-0
lines changed

development/extensions/tutorial_advanced.rst

+169
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ This tutorial explains:
1616
* `Using service decoration`_
1717
* `Replacing the phpBB Datetime class`_
1818
* `Extension version checking`_
19+
* `Implementing Filesystem changes to phpBB`_
1920

2021
Adding a PHP event to your extension
2122
====================================
@@ -526,3 +527,171 @@ branch can be used to provide links to versions in development.
526527
``download`` | "(Optional) A URL to download this version of the extension."
527528
``eol`` | "This is currently not being used yet. Use ``null``"
528529
``security`` | "This is currently not being used yet. Use ``false``"
530+
531+
Implementing Filesystem changes to phpBB
532+
========================================
533+
In certain scenarios, an extension may need to implement filesystem changes within phpBB beyond the extension's
534+
self-contained structure. While this approach is generally discouraged, there are specific conditions where it
535+
may be appropriate. Extensions can safely add or remove files and folders within phpBB’s ``files``, ``images``,
536+
and ``store`` directories, as these are designed to hold user-generated content and are typically not replaced
537+
during phpBB or extension updates.
538+
539+
There are two primary methods for implementing filesystem changes in phpBB through an extension:
540+
541+
1. Using Migrations
542+
2. Using the Extension Enabling Process (ext.php)
543+
544+
Below are examples of how to create a directory named ``my_extension_dir`` in the ``store`` directory for storing additional extension-related files.
545+
546+
Using Migrations
547+
----------------
548+
While migrations are generally designed for database changes, they offer specific advantages when managing filesystem changes:
549+
550+
- Existence Check: Use the ``effectively_installed`` method to check if the files or directories exist already.
551+
- Installation Order: Use the ``depends_on`` method to ensure the directory is created at the correct stage during the extension’s installation process.
552+
- Run separate (optional) filesystem processes during installation and uninstallation.
553+
554+
.. code-block:: php
555+
556+
<?php
557+
558+
namespace acme\demo\migrations;
559+
560+
class add_my_extension_dir extends \phpbb\db\migration\container_aware_migration
561+
{
562+
protected $filesystem = $this->container->get('filesystem');
563+
protected $my_new_dir = $this->container->getParameter('core.root_path') . 'store/my_extension_dir';
564+
565+
public function effectively_installed()
566+
{
567+
return $this->filesystem->exists($this->$my_new_dir);
568+
}
569+
570+
public static function depends_on()
571+
{
572+
return ['\acme\demo\migrations\first_migration'];
573+
}
574+
575+
public function update_data(): array
576+
{
577+
return [
578+
['custom', [[$this, 'add_dir']]],
579+
];
580+
}
581+
582+
public function revert_data(): array
583+
{
584+
return [
585+
['custom', [[$this, 'remove_dir']]],
586+
];
587+
}
588+
589+
public function add_dir()
590+
{
591+
try
592+
{
593+
// Create directory with secure permissions, and add an empty index.htm
594+
if (!$this->filesystem->exists($this->$my_new_dir))
595+
{
596+
$this->filesystem->mkdir($this->$my_new_dir, 0755);
597+
$this->filesystem->touch($this->$my_new_dir . '/index.htm');
598+
}
599+
}
600+
catch (\phpbb\filesystem\exception\filesystem_exception $e)
601+
{
602+
// log or handle any errors here using $e->get_filename() or $e->getMessage()
603+
}
604+
}
605+
606+
public function remove_dir()
607+
{
608+
try
609+
{
610+
if ($this->filesystem->exists($this->$my_new_dir))
611+
{
612+
$this->filesystem->remove($this->$my_new_dir);
613+
}
614+
}
615+
catch (\phpbb\filesystem\exception\filesystem_exception $e)
616+
{
617+
// log or handle any errors here using $e->get_filename() or $e->getMessage()
618+
}
619+
}
620+
}
621+
622+
Using ext.php
623+
-------------
624+
Filesystem changes can also be implemented within the extension’s ``ext.php`` file. This method is preferable if:
625+
626+
- The changes have no specific requirements or dependencies that need monitoring through a migration step.
627+
- The changes should occur at a particular stage, such as enabling, disabling, or deleting the extension.
628+
629+
.. code-block:: php
630+
631+
<?php
632+
633+
namespace acme\demo;
634+
635+
class ext extends \phpbb\extension\base
636+
{
637+
/**
638+
* Add a directory to phpBB's store folder
639+
*/
640+
public function enable_step($old_state)
641+
{
642+
if ($old_state === false)
643+
{
644+
$filesystem = $this->container->get('filesystem');
645+
$my_dir_path = $this->container->getParameter('core.root_path') . 'store/my_extension_dir';
646+
647+
try
648+
{
649+
// Create directory with secure permissions, and add an empty index.htm
650+
if (!$filesystem->exists($my_dir_path))
651+
{
652+
$filesystem->mkdir($my_dir_path, 0755);
653+
$filesystem->touch($my_dir_path . '/index.htm');
654+
}
655+
}
656+
catch (\phpbb\filesystem\exception\filesystem_exception $e)
657+
{
658+
// log or handle any errors here using $e->get_filename() or $e->getMessage()
659+
}
660+
661+
return 'added my_extension_dir';
662+
}
663+
664+
return parent::enable_step($old_state);
665+
}
666+
667+
/**
668+
* Delete a directory from phpBB's store folder
669+
*/
670+
public function purge_step($old_state)
671+
{
672+
if ($old_state === false)
673+
{
674+
$filesystem = $this->container->get('filesystem');
675+
$my_dir_path = $this->container->getParameter('core.root_path') . 'store/my_extension_dir';
676+
677+
try
678+
{
679+
if ($filesystem->exists($my_dir_path))
680+
{
681+
$filesystem->remove($my_dir_path);
682+
}
683+
}
684+
catch (\phpbb\filesystem\exception\filesystem_exception $e)
685+
{
686+
// log or handle any errors here using $e->get_filename() or $e->getMessage()
687+
}
688+
689+
return 'removed my_extension_dir';
690+
}
691+
692+
return parent::purge_step($old_state);
693+
}
694+
}
695+
696+
By leveraging one of these methods, you can implement necessary filesystem changes while maintaining compatibility
697+
with phpBB’s structure and best practices.

0 commit comments

Comments
 (0)