[5.0][Refactoring][Proposal] Consistent file structure for generated classes

[tabacitu]

Currently, Backpack generates

• controllers inside app/Http/Controllers/Admin
• models inside app/Models/
• requests inside app/Http/Requests
• general config files, in config/backpack/
• routes, in routes/backpack/
• views, in resources/views/vendor/backpack/

That’s inconsistent. And 4.0 offers us the opportunity of fixing this inconsistency. I think config files, routes and views are ok the way they are - they’re consistent within themselves. Everything backpack is in a backpack folder.

But classes… not so much. Right now, Backpack Controllers, Models, Requests live inside the main app/Http / app/Models / etc folders. Which makes it easy to understand how they work (which was the point) but makes the separation difficult for big projects. If you have a bunch of entities, you’ll have a bunch of extra controllers and requests. Plus, when you deeply customize the admin panel (with commands, exceptions, middleware, etc) it’s difficult to understand which file is for the admin panel, and which one is for the front-end.

Solution A

How about if, starting with 4.0, we treat the admin panel like it’s a separate app? We can create a new folder at the same level as app that holds all Backpack classes. And for each CRUD, instead of generating

• a controller inside app/Http/Controllers/Admin/
• a request inside app/Http/Requests/

we generate:

• a controller inside AdminPanel/Http/Controllers/
• a request file inside AdminPanel/Http/Requests/
• a crud configuration file inside AdminPanel/Configurations/
• maybe even a model that extends the one in app, so a file in AdminPanel/Models/; so that if you want to change someting inside the model that only applies to the admin panel, you can do that in the extended model, not necessarely in the crud controller;

So basically we’d have this at the same level as app, with exactly the same folder structure as app. It would look like you have two Laravel apps living inside the same project - one for the front-end, and one for the back-end. Which… would be pretty accurate actually… I think that’s a correct way to look at it.

• app
  • Console/
  • Events/
  • Exceptions/
  • Http/
    • Controllers/
    • Middleware/
    • Requests/
  • Jobs
  • Listeners
  • Models
  • Policies
  • Providers
• backend
  • Http
    • Controllers
    • Middleware
    • Requests
  • Library (maybe - for miscellaneous stuff like Elfinder class)
  • Models (maybe - if you want your app/Models intact, you can just extend them here)

I think that would be cleaner than now. It would separate admin panel classes from front-end classes.

Solution B

For that matter, it might make more sense to just put all this content inside a app/Backpack folder, so it would be app/Backpack/Http/Controllers/MonsterCrudController instead of app/Http/Controllers/Admin/MonsterCrudController.

• app
  • Backpack
    • Http
      • Controllers
      • Middleware
      • Requests
    • Models (maybe)
    • Configurations
  • Console/
  • Events/
  • Exceptions/
  • Http/
    • Controllers/
    • Middleware/
    • Requests/
  • Jobs
  • Listeners
  • Models
  • Policies
  • Providers

Solution C

Then again, we could just have a convention that whenever we create a Backpack file, we do it in a Backpack folder, right there. So:

• app
  • Console/
  • Events/
  • Exceptions/
  • Http/
    • Controllers/
      • Backpack/
    • Middleware/
    • Requests/
      • Backpack/
  • Jobs
  • Listeners
  • Models
    • Backpack/ (maybe)
  • Policies
  • Providers

This would probably be the easiest to implement, and the most consistent with how views / configs / routes work, but it would NOT be the cleanest. You still wouldn’t have a folder with all things Backpack...

---

Any opinon on this, anyone? Like/dislike? Thoughts?

[tabacitu]

There’s another option :-)

Solution D - Modules (sort of)

We could organise all files for one CRUD into one folder. This would also make it easy to share CRUDs - just download this zip and put it in the folder, and that’s it. Things like MenuCRUD or NewsCRUD could be delivered that way - since they’re never intended to be updated. And others could be shared this way.

• app
  • Backpack
    • Menu
      • Controllers
      • Requests
    • News
      • Controllers
      • Requests
  • Console/
  • Events/
  • Exceptions/
  • Http/
    • Controllers/
    • Middleware/
    • Requests/
  • Jobs
  • Listeners
  • Models
  • Policies
  • Providers

Don’t know if it’s a good option though :-) Food for thought...

[tswonke]

Currently we use C (for Controllers and Requests).

I have the feeling that D could probably become unhandy as soon as a project is growing.
I tend to A, will talk to @OliverZiegler about that...

[tiagosimoesdev]

I like the idea of modularization . It's easier to mantain in big projects, even in small ones it will keep code well organized . As you said it will be a lot easier to implement one module to another app , that's a big plus .

[promatik]

Either B or C would be great. B keeps the backpack files more organized in the project tree view, but C is more compliant with the Laravel default structure.

[AbbyJanke]

I would prefer either C or D. Typically i structure my projects how C is setup.

Example:

• app
  • Controllers
    • Admin
    • API
    • MyController.php
    • MyController2.php

Essentially the main app (client facing) is in the parent controller folder with the smaller ones which is consistent with Laravel standards and how Taylor does the majority of his projects. However I do like how D is setup and is something i keep coming back to considering as that is how it used to be done on CodeIgniter.

[androidedev]

Solutions A, B or D seems ok to me. The C is the one I like least as it scatter the backpack files throughout the laravel directory structure.

[tabacitu]

Thank you for the feedback guys! Keep it coming :-)

[vesper8]

oh yes please this! I'm really annoyed that the generators currently create files where they do.

I propose a Solution E which takes Solution D to a new level.

Personally this is what I do for all my projects I've made it a point to never use the app folder except for core files (such as EventServiceProvider, Kernel.php, and files in /config/)

Really I think those are almost the only two files that you ever see modified in my projects, this makes it really easy to upgrade to the new laravel releases. I treat all my app-specific code as modules. And I literally store those under a /modules/ folder which is in the root. I then autoload this module in the composer.json using repositories like so:

composer.json

{
    "require": {
        "php": ">=7.1.0",
        ...
        "modules/backpack": "dev-master"
    },
    "repositories": {
        "modules/backpack:     {
            "type": "path",
            "url": "./modules/backpack"
        }
    }
}

I even store composer.json files inside those modules to handle all the dependencies that are installed by that module

Then I use the provider discovery feature of Laravel 5.5 to auto-load the service provider from that module. And in that provider I can load/publish assets, configuration, migrations, routes

I think this is what https://github.com/nWidart/laravel-modules tries to achieve, although I don't use that and came up with my way on my own

Doing it this way.. you could literally put EVERYTHING inside a 'backpack' module. There would be zero need to ever add/generate files outside of this backpack module. The only exception would be to modify the root composer.json which would probably have to be done manually. Or you could do it by having a new backpack-installer package, which could be installed globally, and that would effect the necessary modifications to the root composer.json when called from within a laravel project folder

Let me know if you want more information about how this works.

[hananint]

I second that @vesper8

[tabacitu]

Hmm @vesper8 how would you see Backpack using the modular approach (maybe with https://github.com/nWidart/laravel-modules)? Trying to see if I can learn from your experience with modular Laravel.

A) Would there be one module for the entire admin panel (ex: modules/Backpack) or a module for each crud panel (ex: modules/UserPanel, modules/ArticlePanel, etc).
B) What would happen to Models, which get shared across modules, and even with app if that's still used? Would they live inside app/Models and get reused in modules, or live inside one module and get reused in another module? Say... Tag.

Thanks!

[vesper8]

@tabacitu as I mentioned above, with my proposed solution all Backpack-related code would exist exclusively within a module folder.. such as base_path('modules/backpack')

For this to be possible you would need an installer that would modify the composer.json as I described in my comment above. Then the files created through your crud generator commands (models, controllers, menu, everything) would be created inside the module. All namespaces would also represent this. So a model in /modules/backpack/src/Models/Post.php would be represented with the namespace namespace Backpack\Models;

I wouldn't created separate modules for individual panels. The point is to isolate all the code, no need to overcomplicate things by creating many modules which would bloat up the composer.json

It would be business as usual otherwise, just using different paths for the file generators and different namespaces

You can also place the backpack generated views (such as the menu blade) and the migrations inside this module and then load them through the service provider which would be auto-loaded through the composer.json that's inside the module

The only files that need to exist outside the modules/Backpack module with this solution are files that go in /config/. You may also need to modify the http/console kernel if you want to schedule jobs or add middlewares

I don't know exactly how laravel-modules work, I just created my own modules.

Let me show you what it looks like

Here is a full composer.json for one of my big projects.

{
    "name": "laravel/laravel",
    "description": "The Laravel Framework.",
    "keywords": ["framework", "laravel"],
    "license": "MIT",
    "type": "project",
    "require": {
        "php": ">=7.1.0",
        "addons/backpack": "dev-master",
        "addons/laravel_57": "dev-master",
        "myproject/api": "dev-master"
    },
    "require-dev": {
        "addons/backpack_dev": "dev-master",
        "addons/laravel_57_dev": "dev-master",
        "addons/laravel_dusk_dev": "dev-master"
    },
    "config": {
        "optimize-autoloader": true,
        "preferred-install": "dist",
        "sort-packages": true
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        },
        "classmap": [
            "database/seeds",
            "database/factories"
        ]
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "scripts": {
        "post-autoload-dump": [
            "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
            "@php artisan package:discover --ansi"
        ],
        "post-root-package-install": [
            "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
        ],
        "post-create-project-cmd": [
            "@php artisan key:generate --ansi"
        ]
    },
    "repositories": {
        "myproject/api": {
            "type": "path",
            "url": "./modules/myproject/api"
        },
        "addons/laravel_57": {
            "type": "path",
            "url": "./modules/addons/laravel_57"
        },
        "addons/laravel_57_dev": {
            "type": "path",
            "url": "./modules/addons/laravel_57_dev"
        },
        "addons/laravel_dusk_dev": {
            "type": "path",
            "url": "./modules/addons/laravel_dusk_dev"
        },
        "addons/backpack": {
            "type": "path",
            "url": "./modules/addons/backpack"
        },
        "addons/backpack_dev": {
            "type": "path",
            "url": "./modules/addons/backpack_dev"
        }
    }
}

The addons/laravel / addons/laravel_dev / addons/backpack / addons/backpack_dev are just a way of organizing composer.json dependencies, whereas the myproject/api provides a composer.json with all of my project's custom dependencies as well as all of its code

In your case, the addons/backpack would also contain all of the code that normally gets installed inside the root /app /resources /database

I chose to include another level but you don't have to. My namespace would look like namespace Addons\Backpack\Models but you don't have to do it this way.

This is what the backpack / backpack_dev composer.json files look like:

{
    "name": "addons/backpack",
    "type": "project",
    "version": "dev-master",
    "require": {
        "backpack/crud": "^3.5",
        "balping/json-raw-encoder": "^1.0",
        "barryvdh/laravel-elfinder": "^0.4.1"
    },
    "config": {
        "preferred-install": "dist",
        "sort-packages": true,
        "no-suggest": true
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}

{
    "name": "maddons/backpack_dev",
    "type": "project",
    "version": "dev-master",
    "require": {
        "backpack/generators": "^1.2",
        "laracasts/generators": "dev-master"
    },
    "config": {
        "preferred-install": "dist",
        "sort-packages": true,
        "no-suggest": true
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}

And this is what the folder structure looks like

Hope this helps clear things up, feel free to ask for more detail

[vesper8]

So this is what your composer.json could look like inside /modules/addons/backpack/

{
    "name": "addons/backpack",
    "type": "project",
    "version": "dev-master",
    "require": {
        "backpack/crud": "^3.5",
        "balping/json-raw-encoder": "^1.0",
        "barryvdh/laravel-elfinder": "^0.4.1"
    },
    "require-dev": {},
    "autoload": {
        "psr-4": {
            "Addons\\Backpack\\": "src/"
        }
    },
    "config": {
        "preferred-install": "dist",
        "sort-packages": true,
        "no-suggest": true
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "extra": {
        "laravel": {
            "providers": [
                "Addons\\Backpack\\Providers\\BackpackServiceProvider"
            ]
        }
    }
}

And the inside the service provider you would load migrations, resources, publish commands/configs, etc

[vesper8]

it's up to you how you want to do it and how isolated you want to have it

take for example Laravel Spark which is installed in a similar way, but instead of putting the 'spark' folder in a subfolder called /modules or whatever, it is just added to the root, and then inside the composer.json the spark-installer package adds this entry:

    "0": {
      "type": "path",
      "url": "./spark"
    },

Some of the views are published (copied) to the main resources folder.. perhaps so it is more intuitive for users that want to modify them, while most of the code is run from inside the /spark/ folder. Where the folder sits is irrelevant to what namespace structure you decide to use.. it's all very flexible. The examples I showed above is how I like to organize things but there are many ways to achieve this isolation which is what's most important to me.. to keep all backpack files separate from the "Laravel" files.

[tabacitu]

Got it, thanks a lot for the datails @vesper8 !

[tabacitu]

Guys & gals, just letting you know. It doesn't look like we can cram this into v4. Too many breaking changes already. I want the upgrade process to be relatively simple, and this would add yet another complication to it.

So let's postpone it for v5. Right now it looks like solution C makes the most sense. Which would also be the smallest breaking change, so that's good.

Cheers!