How this plugin handles paths (#25)

* refactor: new way of checking file directory * chore: add php stan and start fixing errors * test: add unit tests * feat: add helper functions and tests * chore: set deprecated filters and add test for one * ci: add unit test runner * docs: update readme and contribution guide --------- Co-authored-by: Mike Sheppard <[email protected]>
smithfield-studio · Nov 8, 2024 · a046667 · a046667
1 parent c0312c4
commit a046667
Show file tree

Hide file tree

Showing 35 changed files with 3,664 additions and 411 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -5,5 +5,8 @@
 /tests export-ignore
 /screenshots export-ignore
 /.github export-ignore
-/phpcs.xml.dist export-ignore
-/LICENSE.txt export-ignore
+/.github export-ignore
+/.phpcs.xml.dist export-ignore
+/.phpunit.xml.dist export-ignore
+/LICENSE.txt export-ignore
+/bin export-ignore
diff --git a/.github/workflows/php-unit-tests.yml b/.github/workflows/php-unit-tests.yml
@@ -0,0 +1,108 @@
+name: PHP unit tests
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**workflows/php-unit-tests.yml'
+      - '**.php'
+      - '**composer.json'
+      - '**phpunit.xml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - '**workflows/php-unit-tests.yml'
+      - '**.php'
+      - '**composer.json'
+      - '**phpunit.xml'
+    types:
+      - opened
+      - synchronize
+      - ready_for_review
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  php-unit-tests:
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mariadb:latest
+        env:
+          MYSQL_USER: root
+          MYSQL_ALLOW_EMPTY_PASSWORD: true
+          MYSQL_ROOT_PASSWORD: ''
+          MYSQL_DATABASE: wordpress_test
+        ports:
+          - 3306
+        options: --health-cmd="healthcheck.sh --connect --innodb_initialized" --health-interval=10s --health-timeout=5s --health-retries=3
+    continue-on-error: ${{ matrix.experimental }}
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.1', '8.2']
+        wp: ['latest', '6.2']
+        multisite: ['0']
+        dependency-version: ['highest']
+        webp: [false]
+        coverage: [false]
+        experimental: [false]
+        include:
+          # PHP 8.2 / experimental
+          - php: '8.2'
+            wp: 'trunk'
+            dependency-version: 'highest'
+            multisite: '0'
+            experimental: true
+          # PHP 8.3 / experimental
+          - php: '8.3'
+            wp: 'trunk'
+            dependency-version: 'highest'
+            multisite: '0'
+            experimental: true
+
+    name: PHP ${{ matrix.php }} ${{ matrix.coverage && ' (with coverage)' || '' }} | WP ${{ matrix.wp }} | ${{ matrix.dependency-version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: ${{ matrix.coverage && 'pcov' || 'none' }}
+          tools: composer:v2
+          extensions: curl, date, dom, iconv, json, libxml, mysql, ${{ matrix.extensions }}
+          ini-values: pcov.directory=src
+
+      - name: Shutdown default MySQL service
+        run: sudo service mysql stop
+
+      - name: Verify MariaDB connection
+        run: |
+          while ! mysqladmin ping -h"127.0.0.1" -P"${{ job.services.mysql.ports[3306] }}" --silent; do
+            sleep 1
+          done
+
+      - name: Setup problem matchers for PHP
+        run: echo "::add-matcher::${{ runner.tool_cache }}/php.json"
+
+      - name: Setup problem matchers for PHPUnit
+        run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
+
+      - uses: ramsey/composer-install@v3
+        with:
+          dependency-versions: ${{ matrix.dependency-version }}
+
+      - name: Install tests
+        run: bash bin/install-wp-tests.sh wordpress_test root '' 127.0.0.1:${{ job.services.mysql.ports['3306'] }} ${{ matrix.wp }} true
+
+      - name: Run tests
+        if: ${{ !matrix.webp }}
+        run: composer run test
+        env:
+          WP_MULTISITE: ${{ matrix.multisite }}
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 vendor
+wp-content
 .phpunit.result.cache
diff --git a/phpcs.xml.dist → .phpcs.xml.dist b/phpcs.xml.dist → .phpcs.xml.dist
@@ -1,26 +1,24 @@
 <?xml version="1.0"?>
 <ruleset>
+
 	<!-- Files or directories to check -->
 	<file>.</file>
-
-   <exclude-pattern>*/wordpress/*</exclude-pattern>
+	<exclude-pattern>*/wordpress/*</exclude-pattern>
+	<exclude-pattern>*/wp-content/*</exclude-pattern>
 	<exclude-pattern>*/vendor/*</exclude-pattern>
 	<exclude-pattern>*/tests/*</exclude-pattern>
 
 	<!-- Path to strip from the front of file paths inside reports (displays shorter paths) -->
 	<arg name="basepath" value="." />
 
-	<!-- Set a minimum PHP version for PHPCompatibility -->
-	<config name="testVersion" value="7.4-" />
-
-   <!-- Use 10up's phpcs ruleset -->
-	<rule ref="10up-Default">
-	</rule>
+  <!-- Set a minimum PHP version for PHPCompatibility -->
+	<config name="testVersion" value="8.1" />
 
+  <!-- Use 10up's phpcs ruleset -->
+	<rule ref="10up-Default"></rule>
 	<rule ref="WordPress.WP.I18n">
 		<properties>
-			<property name="text_domain" type="array" value="acf-svg-icon-picker"/>
+			<property name="text_domain" type="array" value="acf-svg-icon-picker" />
 		</properties>
 	</rule>
-
-</ruleset>
+</ruleset>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,74 @@
+# Contributing to ACF SVG Icon Picker
+
+We welcome contributions to the ACF SVG Icon Picker plugin. This document outlines the process for contributing to the plugin.
+
+## Pull Requests
+
+Pull requests are highly appreciated. To contribute to the plugin, you can fork the repository and create a new branch for your changes. When you’re done, you can create a pull request to merge your changes into the main branch.
+
+1. **Solve a problem** – Features are great, but even better is cleaning-up and fixing issues in the code that you discover.
+2. **Write tests** – This helps preserve functionality as the codebase grows and demonstrates how your change affects the code.
+3. **Write documentation** – Timber is only useful if its features are documented. This covers inline documentation of the code as well as documenting functionality and use cases in the Guides section of the documentation.
+4. **Small > big** – Better to have a few small pull requests that address specific parts of the code, than one big pull request that jumps all over.
+5. **Comply with Coding Standards** – See next section.
+
+## Preparations
+
+After you’ve forked the ACF SVG Icon Picker repository, you should install all Composer dependencies.
+
+```
+composer install
+```
+
+## Coding Standards
+
+We use [EasyCodingStandard](https://github.com/symplify/easy-coding-standard) for Timber’s code and code examples in the documentation, which follows the [PSR-12: Extended Coding Styles](https://www.php-fig.org/psr/psr-12/).
+
+We use tools to automatically check and apply the coding standards to our codebase (including the documentation), reducing the manual work to a minimum.
+
+### Check and apply coding standards
+
+We use EasyCodingStandard to automatically check and apply the coding standards.
+
+```bash
+composer cs
+```
+
+And to automatically fix issues:
+```bash
+composer cs:fix
+```
+
+We also use PHPStan to check for errors in the codebase.
+
+```bash
+composer analyse
+```
+
+## Unit tests
+
+### Install WordPress test suite
+
+Run the following command to install the test suite on your local environment:
+
+```bash
+bash bin/install-wp-tests.sh {db_name} {db_user} {db_password} {db_host} {wp_version}
+```
+
+Replace variables with appropriate values. for example:
+
+```bash
+bash bin/install-wp-tests.sh acf_icon_test root root localhost 6.6
+```
+
+### Run unit tests
+
+Run PHPUnit test suite with the default settings and ensure your code does not break existing features.
+
+```bash
+composer test
+```
+
+## Process
+
+All PRs receive a review from at least one maintainer. We’ll do our best to do that review as soon as possible, but we’d rather go slow and get it right than merge in code with issues that just lead to trouble.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 
 # ACF SVG Icon Picker Field
 
-Add an ACF field to your theme that lets users easily select SVG icons from a specified folder. The field returns the SVG's name.
+Add a field type to ACF for selecting SVG icons from a popup modal. Theme developers can provide a set of SVG icons to choose from.
 
 ## Compatibility
 
@@ -35,59 +35,51 @@ If you're coming from the original ACF Icon Picker plugin, you can switch to thi
 4. Go over your field configurations and change the field type from `icon-picker` to `svg_icon_picker` in the field settings. Be aware of the underscores in the field type name.
 5. Check if the field type is now available in your ACF field settings
 
-## Filters
+## Usage of this plugin
+We recommend storing your SVG icons in a folder within your theme. This plugin defaults to looking for icons inside the `icons/` folder of your theme. You can change this path by using the [`acf_icon_path_suffix` filter](#filters).
 
-Use the below filters to override the default icon folder, path, and / or URL:
+When using this plugin in conjunction with a parent/child theme, you can store your icons in the parent theme and use the child theme to override the path to the icons. This way, you can provide a set of icons in the parent theme and still allow the child theme to override them.
+
+### Helper functions
+We provide helper functions to fetch icons from the theme folder, without it mattering if the icon is stored in the parent or child theme.
 
 ```php
-// modify the path to the icons directory
-add_filter('acf_icon_path_suffix', 'acf_icon_path_suffix');
+$my_icon_field = get_field('my_icon_field');
+
+// Get the icon URL
+$icon_url = get_svg_icon_uri($my_icon_field);
 
-function acf_icon_path_suffix($path_suffix) {
-    return 'assets/img/icons/';
-}
+// Get the icon file system path
+$icon_path = get_svg_icon_path($my_icon_field);
 
-// modify the path to the above prefix
-add_filter('acf_icon_path', 'acf_icon_path');
+// Get the icon contents
+$icon_svg = get_svg_icon($my_icon_field);
+```
 
-function acf_icon_path($path_suffix) {
-    return plugin_dir_path(__FILE__);
-}
+### Filters
 
-// modify the URL to the icons directory to display on the page
-add_filter('acf_icon_url', 'acf_icon_url');
+Use the below filters to override the default icon folder inside your theme.
 
-function acf_icon_url($path_suffix) {
-    return plugin_dir_url( __FILE__ );
-}
+```php
+// modify the path to the icons directory in your theme.
+add_filter('acf_icon_path_suffix', function () {
+  return 'resources/icons/';
+});
 ```
 
-### For Sage/Bedrock edit filters.php:
+In case you do not want to store the icons in the theme folder, you can use the filter below to change the path to an icons directory in a custom location.
+In this example, the icons are stored in the `WP_CONTENT_DIR . '/icons/'` folder.
 
 ```php
-/// modify the path to the icons directory
-add_filter('acf_icon_path_suffix',
-  function ( $path_suffix ) {
-    return '/assets/images/icons/'; // After assets folder you can define folder structure
-  }
-);
-
-// modify the path to the above prefix
-add_filter('acf_icon_path',
-  function ( $path_suffix ) {
-    return '/app/public/web/themes/THEME_NAME/resources';
-  }
-);
-
-// modify the URL to the icons directory to display on the page
-add_filter('acf_icon_url',
-  function ( $path_suffix ) {
-    return get_stylesheet_directory_uri();
-  }
-);
+add_filter('acf_svg_icon_picker_custom_location', function () {
+  return [
+    'path' => WP_CONTENT_DIR . '/icons/',
+    'url' =>  content_url() . '/icons/',
+  ];
+});
 ```
 
-## Using with [ACF Builder](https://github.com/StoutLogic/acf-builder) / [ACF Composer](https://github.com/Log1x/acf-composer)
+### [ACF Builder](https://github.com/StoutLogic/acf-builder) / [ACF Composer](https://github.com/Log1x/acf-composer)
 
 ```php
 $fields->addField('my_icon', 'svg_icon_picker', [
@@ -99,6 +91,7 @@ $fields->addField('my_icon', 'svg_icon_picker', [
 Updated to work with ACF v6.3 and above.
 
 ## Changelog
+[See Releases for the full changelog](https://github.com/smithfield-studio/acf-svg-icon-picker/releases) (since forking from [houke/acf-icon-picker](https://github.com/houke/acf-icon-picker))
 
 * 3.1.0 - Changed name of field to `svg_icon_picker` to avoid conflicts with vanilla ACF Icon Picker field.
 * 3.0.0 - Revert to original ACF field name, quick tidy + README updates