Customising name­spaces in Symfony apps

After you’ve installed Symfony you’re greeted with the default “App\” root namespace. But “App” is not a suitable choice if you practise domain-driven design (DDD) and when you prefer a namespace that is unique to your project. Unfortunately, you cannot configure the root namespace up-front and Symfony folks apparently don’t see how this could be useful.

When you create hexagonal architectures for domain-driven design, you already have “app” or “application” directories for your application layer inside every domain. With an “App” root, you’d end up with awkward namespaces like “App\DomainOne\App”. But even if you’re not into DDD, you might still prefer a more specific root like “MyBusiness\ClientProject”.

Attempting to modify your PSR-4 namespace roots through Composer will cause issues with Symfony’s auto-wiring, since the root namespace has been hard-coded in various locations. As I always forget where these hard-coded instances are located and the process of replacing them can be quite tedious, this quick guide aims to help me. Sorry, you 🙂

For this guide we’ll assume that you have changed your root namespace to “Universe\PlanetEarth\”, meaning that in composer.json you have configured your PSR-4 namespaces as follows. Kindly note the double backslashes you need to use for your psr-4 definitions:

{
"autoload": {
        "psr-4": {
            "Universe\\PlanetEarth\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Universe\\PlanetEarth\\Tests\\": "tests/"
        }
    }
}

If you use Phpstorm, make sure your configured directories (Settings\Directories) match the namespaces. Phpstorm sometimes gets confused and doesn’t update them properly. Additionally, force Phpstorm to re-index your project through “File\Invalidate caches…” to teach auto-complete your new namespaces. Simply closing and reopening the project will not trigger re-indexing.

In your Symfony project follow these steps:

1. Go to planetearth\src and change the namespace for Kernel.php from “App” to “Universe\PlanetEarth\”.
2. For the courageous: Run a case-sensitive(!) find+replace for the “App\” namespace on your project excluding the vendor folder(!)
3. For everyone else or if you just wish to check you caught all occurrences:
   1. Replace the “App\Kernel” namespace with “Universe\PlanetEarth\Kernel” in
      • planetearth\src\bin\console.php
      • planetearth\src\public\index.php
   2. Adjust your settings in:
      • planetearth\src\config\services.yaml: Replace “App\” under “Services”
      • planetearth\src\config\routes.yaml: Change the namespace for your controller resources. If this is a fresh install, there is only one.
      • planetearth\src\config\packages\doctrine.yaml: Adjust your orm mappings (names and prefixes) as desired
   3. In your test environment config .env.test change the KERNEL_CLASS to “Universe\PlanetEarth”

Update composer.json and make sure that you don’t get any error messages complaining about msiconfigured paths or missing resources. And this should do 🙂