I know that PHPUnit is the most widely used testing suite out there, but I (and some others here and there) have made a conscious choice to use PHPSpec, which accomplishes basically the same thing but with a different (and in my opinion, better) grammar. It doesn't call it's code "tests" but rather "specs" to point out that what you write are specifications of what output is expected for certain input. And as such, in contrast to PHPUnit, it automatically uses a "specs" directory to hold that code. So because of that, none of my projects will have a "tests" directory.

I would also mention Behat, which uses a "features" directory for its own set of reasons.

Is there some way an allowance for this kind of thing could be worked into the standard?

If a package provides a CLI, it's binary or binaries MUST BE located under the /bin directory and MUST BE configured as a vendor binary in the package its composer.json.

While libraries shouldn't commit the vendor directory to version control, there are instances where it might be beneficial for projects to commit the vendor directory.

Open for discussion, consider revising the vendor/ section to read:

The vendor/ directory MUST be reserved for use by package managers (e.g.: Composer).

If the repository type is designated as a "project" in its composer.json file, the vendor/ directory SHOULD be ignored by revision control tools (e.g.: Git, Mercurial, Subversion, etc.). It SHOULD NOT be committed to revision control repositories.

If the repository type is designated as a "library" (the default) or otherwise in its composer.json file, the vendor/ directory MUST be ignored by revision control tools (e.g.: Git, Mercurial, Subversion, etc.). It MUST NOT be committed to revision control repositories.

This publication does not otherwise define the structure and contents of the directory.

I know that not every application needs templates or views. So it shouldn't be a MUST. But I would prefer a suggestion how to name such a folder because I have seen so many different names in the wild.

• view
• views
• templates
• template
• tpl
• tpls
• ...

Wouldn't the quite popular build folder be a candidate for inclusion? I guess it didn't show up in the research data, as most projects only create it while building and delete it again afterwards.

But nonetheless it is quite common in many build automation tools, continuous integration tools and projects like this one, for example.

What about adding a SHOULD to the section about the LICENSE file? I know there are some companies out there that have legal departments that get heartburn over this kind of stuff, and encouraging people to explicitly state a license seems like a worthy endeavor.

I'd like to propose the addition of the resources folder to this standard.

The resources folder, to me at least, is a folder where one can store non public, non 100 % source code" related resource material/assets etc. For example, We used such a folder for storing vendor XML schema files for a XML API client library we recently developed.

While I agree, it is not a very common folder, it is still a quite common enough one, as you can see by your own research data:

• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L4 Resources/ 5969
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L22 resources/ 1424
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L859 ressources/ 6
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L937 Ressources/ 5
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L328 resource/ 29
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L401 Resource/ 21

Total "resources" related: 7454

Through your iteration steps, though, you only considered the resources variant with 1424 occurrences. https://github.com/php-pds/skeleton_research/blob/1.x/results/02-dirs.txt#L82

This might be an addition for a later version of this standard, though.

Hi @pmjones

Thank you for your research and work on this.

Personally, I'm a big proponent of such a minimalistic standard. I contributed to thephpleague/skeleton in the past and even setup a small skeleton for CakePHP 2.x Plugins.

Since I support such an endeavor, I had a discussion about your standard with my team. They all support it, though it became clear, that the public folder was the only one that is kind of controversional.

While I guess almost all of your proposed folders and files are already nearly de-facto standards or could become a standard without much of a fuzz, the public folder is the one where many devs will have a diverging opinon about.

This could be because their framework simply demands them to put their public html stuff in a differently named folder or simply because of long time habits.

Anyway, it would be really sad, if people can't adopt the standard, because they cannot adhere to your public folder requirement.

And the way, how the draft is worded right now, it is a requirement:

https://github.com/php-pds/skeleton#public

If the package provides a directory for web server files, it MUST be named public/.

That's why I really recommend you to not include the public folder with a MUST but wit a RECOMMENDED wording.

This way, your standard gets adoption very easily.

And if the PHP community settles on this matter in a nearby future, you can include the plugin folder with a MUST in a later version of the stardard.

It's way easier to evolve a standard over time than trying to revolutionize with it.

Release/dist packages MUST NOT contain repository meta data files like CONTRIBUTING , README, command-line executables related to the package its release process, and so on.

See LeanPackageValidator for more details.

It would be useful to ship this package with a validator based on the recommendations. A simple compliance report would then be displayed to the user.

I'm happy to help create this, if people agree to this feature.

I took a closer look at this standard and found one aspect of it to be lacking.

I read the discussion about resources in #12 - I understand that it's common to have a folder named "resources", but I don't feel like the definition of it is meaningful.

The term "resource" at the moment is is very broadly defined as:

If the package provides a root-level directory for other resource files, it MUST be named resources/

This is so broad it's almost conflicting with the description of "other directories":

The package MAY contain other root-level directories for purposes not described by this publication.

All I can surmise from these two descriptions is that "other files" may go either into "resources" or into "other directories".

In other words, the description appears to indicate that I gather is probably true, that even if many projects have a folder named resources, the use of this folder is completely arbitrary - just the same as use of "other directories".

So it's kind of already covered by "other directories", and there is no clear definition of what (if anything) should go into "resources", I think because the term "resource" is essentially every bit as broad as the term "file" - since the whole point of this standard is to help figure out how to structure the project's files/resources/assets/whatever, it seems more confusing than helpful to reserve a specific folder for "stuff", and at the same time have a clause that allows for any other root folder-name for "other stuff".

Which brings me to the thing I didn't find as part of this specification.

In our own internal folder-names specification for our projects, we have three reserved folders for "other files", but with a very important distinction, not regarding the type of files/resources that get put into those folders, but with a designated definition of the nature or origins of those "other files".

In particular, I find that this proposed standard defines nothing with regards to dynamic files, so I will try to address that with the following suggestion.

Not minding the folder-names we happen to use, and with attention to the folder-names and definitions already defined by this standard, I'd suggest the following:

1. Change the definition of resources, such that this folder is reserved for permanent, static files - this could be scripts or other data-files under source-control, containing data-dependencies, which are loaded/parsed or otherwise required by the project.

2. Add a reserved folder for run-time files, e.g. named runtime - this would be the designated root-folder for run-time generated artifacts, typically cache-files for computed data, images, log-files, temporary uploaded files, etc. This folder must be writable by the application, and all files should be considered volatile or transient, meaning you can erase the contents of this folder at any time without affecting the functionality of the application. (This is different from a system-defined "temp" folder, since e.g. log-files etc. could be important for diagnostic purposes, and since e.g. clearing the cache of a specific application may briefly affect the performance of that application.)

3. Add a reserved folder for permanent assets, perhaps named assets (though this could be somewhat ambiguous with "web assets" such as CSS/JS files, so I'm definitely open to other ideas) - this would be the designated default root-folder for user-generated, permanent assets, such as uploaded images or other documents, and any other non-volatile data; resources that are critical to the functioning of the application and must not be erased.

I'm merely spit-balling as far as the actual folder names here, just for the sake of discussion.

I believe (2) and (3) are important because of things like:

• folder-permissions - applications need write-access to these folders; because users need to know which folder is safe to clear when the application accumulates too much junk or when there's an apparent cache-problem; and because developers need to know where to look for artifacts such as log-files etc. for diagnostic/debugging purposes of applications in production, and
• source-control - you may or may not wish to store run-time and permanent assets under the application project folder itself, but it's common enough, and often is the default, even if most projects make this configurable; developers need to know which folders to exclude from source-control and/or IDE analysis etc.

I haven't looked at existing applications or frameworks to see how these folders are named, but I believe it's a fact that most (if not all) web-applications (at least) have designated folders for permanent and run-time data, as most applications do have both some kind of cache-folder and a folder for user-generated files.

I'm guessing it would take more than a statistical survey to propose specific folder-names for (2) and (3) but at this stage merely wanted to explain why I think these two folder-designations are important - even if there is no statistical common average for the naming of these folders, in my experience, most projects have them, and I think it would be useful to define these.

I'm hoping the purpose of this specification is to establish more than a formalization of an existing de-facto standard for project structure, and so I feel that this may be an extremely important missing piece of the puzzle.

Let me know what you think?

Fixes a number of bugs from #43:

• Check whether the specified folder exists and that it has sufficient permissions.
• Output a message specific to each of the errors above.
• Existing folders and files do not cause a warning.
• Existing files do not get overridden.
• Add tests to prove the bugs in #43.

Added a few examples, since people will keep asking. We still have This publication does not otherwise define the structure and contents of the directory, so the spec remains reasonably neutral in that regard.

Fixes #36

First of I want to say thanks for this work!

I'm still relatively a beginner developer. From reading this standard it appears to me that a "resources" directory is analogous to a "vendor" directory in a composer project. (I could be completely wrong)

Considering the relative popularity of composer in PHP projects, how does this standard reconcile the two? Should the "vendor" directory substitute the "resources" directory in a composer project?

Can the two folders be seen as conceptually being the same?

I put all my autoloaded classes into /src. But where do I put the source for my main* for a command-line executable? Does that go in /src? Someplace else?

*main (like int main() in C/C++) -- the non-class entry point for the program, which typically receives the command line parameters via $argv.

Are the command-line executables which belong in /bin those which are delivered as part of the package? Or are they executables which are generated by the package, after delivery and installation, via some user-invoked means? Or both?