Skip to content

Add composer installation to docs/welcome #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: trunk
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 125 additions & 4 deletions docs/welcome/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,132 @@ Before installing, ensure your site meets these requirements:
2. Extract the plugin files
3. Upload the plugin folder to `/wp-content/plugins/`
4. Activate through the WordPress admin interface
---

## Verification
### Composer Installation

To install and manage Secure Custom Fields in your WordPress theme or plugin, it is recommended to use Composer.

This ensures that SCF is properly versioned, loaded automatically, and easy to update.

### Why integrate **Secure Custom Fields (SCF)** with Composer?

Integrating SCF using Composer offers several important advantages for the professional development of WordPress plugins and themes:

- **Centralized dependency management:**
Composer allows you to declare, install, and update SCF easily along with other libraries needed in your project.

- **Version control:**
You can lock a specific version of SCF in your `composer.json`, ensuring that all development and production environments use exactly the same version, avoiding unexpected errors.

- **Simplified deployment and automation (CI/CD):**
Composer installs SCF automatically during deployment processes (`composer install`), eliminating the need to manually copy files.

- **Automatic autoloading:**
Composer handles PHP class autoloading. Integrating SCF this way makes your code cleaner, safer, and PSR-4 compliant.

- **Reduced repository size:**
By installing SCF as an external dependency, you avoid having redundant copies of the plugin in your project, keeping your repository lighter and easier to maintain.

- **License compliance:**
Composer records the licenses of all dependencies used, which is very useful if you distribute your plugins or themes and need to meet legal or auditing requirements.

- **Facilitates project changes:**
By managing SCF as a dependency, any theme or plugin can change its structure or installation system without affecting its functionality, ensuring greater flexibility and compatibility in development.

---

### How to Load and Use **Secure Custom Fields (SCF)** with Composer

Add the following configuration to your `composer.json` file:

```json
{
"repositories": [
{
"type": "composer",
"url": "https://wpackagist.org"
}
],
"extra": {
"installer-paths": {
"vendor/{$name}/": ["type:wordpress-plugin"]
}
},
"require": {
"wpackagist-plugin/secure-custom-fields": "6.4.1"
},
"config": {
"allow-plugins": {
"composer/installers": true
}
}
}
```
Once the configuration is set, run the following command in your terminal to install the dependencies:
```shell
composer install
```
or
```shell
composer i
```
---
### Add the Composer Autoloader
To ensure Composer dependencies are loaded correctly, add the following line in your plugin or theme:
```php
require_once plugin_dir_path(dirname(__FILE__)) . 'vendor/autoload.php';
```
### Load Secure Custom Fields
Now you need to manually load the Secure Custom Fields plugin and define its paths. Adjust the paths according to the structure of your plugin or theme:
```php
if (! class_exists('ACF')) {
// Define the path and URL to the Secure Custom Fields plugin.
define('MY_SCF_PATH', plugin_dir_path(dirname(__FILE__)) . 'vendor/secure-custom-fields/');
define('MY_SCF_URL', plugin_dir_url(dirname(__FILE__)) . 'vendor/secure-custom-fields/');

// Include the plugin main file.
require_once MY_SCF_PATH . 'secure-custom-fields.php';
}
```
⚠️ **Note:** Replace MY_SCF_PATH and MY_SCF_URL with constants that match your plugin/theme structure if necessary.

### Done!
You have successfully installed and integrated Secure Custom Fields via Composer. You can now use it as you would with a normal installation, but with all the benefits of Composer-based dependency management.

---

### Optional: Hide SCF Admin Menu and Updates

If you want to hide the **Secure Custom Fields (SCF)** admin menu from the WordPress dashboard and prevent the plugin's update notifications from appearing, you can use the following code:

```php
// Hide the SCF admin menu item.
add_filter( 'acf/settings/show_admin', '__return_false' );
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be careful not to suggest always disabling the admin menu: what if the site using the plugin/theme uses SCF anyway?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@priethor You're right, I think this should be an optional step, I'll modify it in a new commit.

Copy link
Contributor

@priethor priethor Apr 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same goes for plugin updates. I think it should be checked whether SCF is already installed with get_plugins() before trying to hide either.


// Hide the SCF Updates menu.
add_filter( 'acf/settings/show_updates', '__return_false', 100 );
```
#### What does this do?

- **Hide Admin Menu:**
The first filter disables the SCF menu in the WordPress admin area, preventing users from accessing SCF field groups or settings.

- **Hide Update Notifications:**
The second filter disables the SCF update notices, so users won't see update prompts for the plugin inside the admin dashboard.

#### When should you use it?

- If you are bundling SCF inside your plugin or theme and want to **control all the custom fields yourself** without allowing clients or users to modify them.
- If you want to **maintain full control** over SCF versions and updates to avoid compatibility issues caused by manual updates.

> **Note:** Hiding updates means you are responsible for manually updating SCF when necessary to keep your project secure and compatible.


## Verify Your Installation

After installation:

1. Navigate to Custom Fields in your admin menu
2. Verify you can access all plugin features
3. Create a test field group to ensure functionality
1. Navigate to **Secure Custom Fields** in your WordPress admin menu.
2. Verify that you can access all **Secure Custom Fields** plugin features.
3. Create a **test field group** to ensure that fields are saved and displayed correctly.
Loading