aklump/htaccess-manager

0.0.9 2026-02-16 18:20 UTC

Requires

• php: >=7.4
• ext-curl: *
• ext-json: *
• aklump/json-schema-loading: ^0.0
• aklump/json-schema-merge: @dev
• aklump/json-schema-validation: ^0.0
• symfony/console: ^4.4 || ^5.4 || ^6
• symfony/filesystem: ^4.4 || ^5.4 || ^6
• symfony/http-foundation: ^4.4 || ^5.4 || ^6
• symfony/yaml: ^4.4 || ^5.4 || ^6

Requires (Dev)

• aklump/phpswap: ^0.0.8
• composer/composer: *
• phpunit/phpunit: ^9.6

BSD-3-Clause

• Aaron Klump

README

Summary

A PHP tool for .htaccess management in your web projects.

• Allows you to include .htaccess files in other .htaccess files.
• Work with smaller files then combine using ./bin/htaccess build
• Share common snippets across different .htaccess files.
• Simplified URL redirection; remap old URLs to new without nasty syntax.
• Merge in remote .htaccess source files on build (think Drupal web root .htaccess + custom .htaccess directives).
• Manage banned IPs in a separate file or add them to the YAML configuration.

Quick Start

• Create a YAML configuration file in a secure location in your project.
• Refer to config.example.yml as a guide and optionally, delete when done.
• Lastly, build your files using ./vendor/bin/htaccess build path/to/your/config.yml

Install with Composer

1. This package requires some unpublished packages. You must add the following to composer.json in the repositories array:

   {
    "type": "github",
    "url": "https://github.com/aklump/json-schema-loading"
   },
   {
    "type": "github",
    "url": "https://github.com/aklump/json-schema-validation"
   },
   {
    "type": "github",
    "url": "https://github.com/aklump/json-schema-merge"
   }

2. Require this package:

   composer require aklump/htaccess-manager:^0.0
   

Configuration Special Notes

• You must list one or more hosts in valid_hosts, including their http or https protocol.
• Forced SSL redirection is detected based on the valid_hosts array; force_ssl will be set to true if all valid_hosts use the https protocol. You may override auto-detection by setting force_ssl to true or false.
• Adding or removing www. is detected based on the valid_hosts array. It is set to add if all valid_hosts have www., remove if all valid_hosts do not have www.. When neither add nor remove no redirection takes place. You may override auto-detection by setting www_prefix to add, remove, or default.

Usage

• To view help execute ./vendor/bin/htaccess

Environment Variable Substitution

The configuration file supports environment variable substitution. You can use $VAR_NAME or ${VAR_NAME} syntax in both keys and values of the YAML file. Using ${VAR_NAME} is recommended to avoid ambiguity when a variable is immediately followed by other characters. This is useful for creating template-like configurations that can be customized per project.

files:
  ${PROJ_ID}:
    title: $PROJ_TITLE
    valid_hosts:
      - https://example.com
    output:
      - ${PROJ_DIR}/web/.htaccess

When running the build command, provide the environment variables:

PROJ_ID=myproject PROJ_TITLE="AKlump's Web Factory" PROJ_DIR=./path ./bin/htaccess build config.yaml

Sponsor this project

 github.com  buymeacoffee.com  paypal.com

More Reading

• THE Ultimate Htaccess
• Mod_Rewrite Variables Cheatsheet
• Htaccess

Troubleshooting

4xx redirects are not working

I'm not sure why, but on some servers they do not work. Possible reasons:

1. Apache version?
2. VirtualHost config hijacking?
3. Drupal conflict?