Application structure proposal

[kevindierkx]

I was running trough te code and noticed some mix matching of different concerns, like adding HTML inside a controller and mounting a route inside the bootstrapping code. #51 removed some of it for example.

Proposal

Keeping maintainability in mind mix matching isn't a good practice, separating the code would make it easier to extend the application to add new features and/or maintain the application without searching for the problem for a while before being able to fix it.

Proof of concept

Providing some kind of example is always beter than just a wall of text, therefore I've made a head start by creating a proof of concept: kevindierkx/satisfy
Please note this is an early draft, most files still should be removed or refactored.

Further explanation about the different components are described below.

Bootstrapping, Services and Providers

Providers provide an easy way to register and bootstrap services, like the Twig rendering for example. There is already a custom SatisServiceProvider available providing the satis file formatting and some other stuff.

I also would like a to provide the application routes this way. The RouteServiceProvider.php provides the routes by loading a .yml file containing the route definitions. In my opinion this is the clearest way to provide routes for this application, Silex provides a ControllerProviderInterface, but that doesn't really has an added benefit for this use-case if you ask me.

In addition a Container service globally registering the application instance would be helpful. This provides easy access to the current application instance later on in the application's lifetime.

Helper methods

I don't like defining the same thing over and over again, therefore I've added a helpers.php in the bootstrap folder.

This file utilises the Container service described in the previous paragraph and provides some methods for easy access to the different application paths. For example you can use app_path() to get the app folder path, resources_path() to get the resources folder path and app() to access the current application instance, just to name a few.

These methods can be used anywhere in the application.

Directory structure

Silex doesn't really require a specific directory structure by default. This makes it super flexible for different tasks, but somewhat confusing when creating a more complex application.

Therefore I suggest a slightly modified directory structure, making room for centralised config files and storage folders. ie. recovery points, logs and in the future file based sessions if required.

/app
    |- Controllers
    |- Forms
    |- Models
    |- Providers
    |- Services
    |- Validators
/bin
/bootstrap
/config
/resources
/storage
    |- logs
    |- recover
/tests
/web

App

The app folder is where the magic happens, here goes all the application logic that should be tested. Controllers, Forms, etc all have their own namespace making it clear where something goes and what its purpose is.

Bin

The bin folder contains the Satis 'proxy'. By proxying the Satis command we can add some custom exception logic making it easier to display errors to the end user. See #53 for more information about logging.

Bootstrap

The bootstrap folder only contains bootstrapping logic, registering providers and setting up the application session.

Config

The config folder contains the application config, that shouldn't be changed during runtime.

Resources

The resources folder contains application resources like translation files and twig templates just to name a few.

Storage

The storage folder contains application logs, recovery points and file based sessions/cache if required.

Tests

The tests folder contains test files for the application.

Web

The web folder is the public root directory for the webserver.

[ramunasd]

It's a nice work, well done @kevindierkx :)

Despite of your work, i'd like to switch to symfony 3. Then we could get rid of this "bootstrap" stuff, helpers, global variables and etc...

[kevindierkx]

@ramunasd Thanks for the input! Switching to Symfony 3 would do almost the same as I just did with my proof of concept.
However it doesn't get rid of the 'bootstrap stuff' it just places it in a different place like the app.php in this demo app.

Beside it not being necessary the helpers file would still come in handy when accessing the satis.json or some kind of resource anywhere in the application. I took the idea from laravel/laravel btw.

In the end it depends on which dependencies we require in the application, I don't think a full stack framework is required for adding some entries to a JSON file.

I would like to hear your thoughts about this!

[ramunasd]

Well, yes, it makes sense at some points. From what i see this application is growing to something more than just "adding some entries to a JSON file". It's very clear that we need add "must have" features like

• github/bitbucket hooks
• control of all satis options
• automatic tasks with background workers

We can make all these features and even more with silex. The questions is how fast we can go further with silex? symfony? laravel?

[ramunasd]

https://github.com/terramar-labs/packages is alternative to satisfy, you can get impression on what is important to have in such applications

[kevindierkx]

I agree the application could benefit from a full stack framework. I wouldn't mind using a full stack framework in the near future.

For now the directory structure needs changing anyway if you use Symfony or Laravel they both have a bootstrapping process, the proof of concept mentioned in the issue resembles the booting process of both frameworks. (Minor naming convention stuff left aside)

I would like to make a start with the logging mention in #53 this partly depends on some of the refactoring made in the proof of concept.

Might I suggest making a roadmap/whishlist with the wanted features? We can make an informed decision about what kind of toolkit we need after we decided what we actually want to build.

I'll continue work on the POC making a fully working example, this only needs some code being moved.

[ludofleury]

Hey guys,

Satisfy started really humble, to fill a quick gap. I didn't check the
alternative. But what we could start with is a roadmap of features. Let's
put in a specific issue everything and discuss it then organize a milestone
around it.

The tech choice will follows quickly and match the needs.

On Tue, 9 Feb 2016 at 16:05, Kevin Dierkx [email protected] wrote:

I agree the application could benefit from a full stack framework. I
wouldn't mind using a full stack framework in the near future.

For now the directory structure needs changing anyway if you use Symfony
or Laravel they both have a bootstrapping process, the proof of concept
mentioned in the issue resembles the booting process of both frameworks.
(Minor naming convention stuff left aside)

I would like to make a start with the logging mention in #53
#53 this partly depends on
some of the refactoring made in the proof of concept.

Might I suggest making a roadmap/whishlist with the wanted features? We
can make an informed decision about what kind of toolkit we need after we
decided what we actually want to build.

I'll continue work on the POC making a fully working example, this only
needs some code being moved.

—
Reply to this email directly or view it on GitHub
#54 (comment).

[kevindierkx]

@ramunasd, @ludofleury Alright I've finished the application structure refactor as you can see in #56. If you guys could take a look and let me know what you think that would be greatly appreciated.

[ramunasd]

For me it does not makes sense to move models and forms to another namespace. Form became Forms and Model to Models - is there any serious reason to change this?

Also i'd like to keep sources in src like it was before. I think it is convenient way in php community.

Regarding satis.json. Well, if You want to move it to another place, then this should be documented. Also this creates issues with default values in command bin/satis build. It was very comfortable to rerun build without any arguments.

I think this change is too big and has too much BC. Some parts does not follow common conventions.

[kevindierkx]

The namespace changes are mainly convention (in our company anyway), the folders/namespace contains multiple models therefore I've used the plural form of model/form. This is common practice in most Laravel applications, however I don't mind changing it back to its respective noun.

Regarding the src folder I agree it's widely used in PHP 'components' however in an application it doesn't make any sense and just makes your folder structure more complex. With the introduction of PSR4 you can define the starting point of your namespace perfectly fine. The only reason you would like to keep the src folder structure is for something that doesn't support PSR4.

The satis.json is a core component of the app and should be handled like one, therefore I've moved it to a more prominent and logical place.
You can easily modify the provided bin/satis file to autocomplete those parameters to the applications default ones. This is also needed for the logging I'm planning in #53. This should resolve most BC changes after we've done so.

Regarding documentation, since it's in a proposal stage I haven't spend the time to write documentation for something that could still change. If we agree these changes are acceptable I wouldn't have a problem adding them.