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.

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?

Hello!

I like having a directory with small examples of how to use my libraries.
I use the example directory in the root
Am I wrong or not?

docs/
examples/
src/
tests/

I would love to see a standard temp and cache and log files directory.

For example:

tmp/          # temp files
tmp/cache/    # internal cache files
tmp/log/      # log files

or just like this

tmp/          # temp files
cache/        # internal cache files
log/          # log files

SQLite databases can be included directly in the PHP project repository.

Here is one example: https://github.com/fulldecent/19-questions (local/database.db).

Is there or should there be a defined location for such files?

Note: configuration files and databases are similar in that they will have different versions between production and QA deployments. Also, they will both be excluded in .gitignore.

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.

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
• ...

can you release the fixes?
because composer will pull release, and that is buggy ($lines = $validator->getFiles(); in PackageGenerator instead of passing $root to it)

I think we should change these terms:

resources -> res (like bin, config, doc, etc...)
tests -> test
docs -> doc

Like most of languages...

When trying to generate the structure for a new project, I get a bunch of error messages...

php vendor/bin/pds-skeleton generate xxx
PHP Warning:  mkdir(): File exists in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29

Warning: mkdir(): File exists in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29
PHP Warning:  mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29

Warning: mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29
PHP Warning:  mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29

Warning: mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29
PHP Warning:  mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29

Warning: mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29
PHP Warning:  mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29

Warning: mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29
PHP Warning:  mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29

Warning: mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29
PHP Warning:  mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29

Warning: mkdir(): Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 29
PHP Warning:  file_put_contents(/CHANGELOG.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34

Warning: file_put_contents(/CHANGELOG.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34
PHP Warning:  chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35

Warning: chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35
PHP Warning:  file_put_contents(/CONTRIBUTING.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34

Warning: file_put_contents(/CONTRIBUTING.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34
PHP Warning:  chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35

Warning: chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35
PHP Warning:  file_put_contents(/LICENSE.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34

Warning: file_put_contents(/LICENSE.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34
PHP Warning:  chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35

Warning: chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35
PHP Warning:  file_put_contents(/README.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34

Warning: file_put_contents(/README.md): failed to open stream: Permission denied in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 34
PHP Warning:  chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35

Warning: chmod(): No such file or directory in /tmp/test/vendor/pds/skeleton/src/PackageGenerator.php on line 35
Created /bin
Created /config
Created /docs
Created /public
Created /resources
Created /src
Created /tests
Created CHANGELOG.md
Created CONTRIBUTING.md
Created LICENSE.md
Created README.md

It looks like a permission problem. But it seems that the generator expects that the folder "xxx" already exists.

The following works:

mkdir yyy
php vendor/bin/pds-skeleton generate yyy

Perhaps the discussion on /src should prescribe that a PSR-4 autoloader should be used.

I wanted to bring up a really good blog post comment on your blog post about this standard:

Fabian
2016-12-16 at 05:55
I really like that small standard. I suggest putting it into “provide” (https://getcomposer.org/doc/04-schema.md#provide) instead of “require-dev”, so you can track formal adoption (e.g. https://packagist.org/providers/psr/log-implementation)?

Totally agree, as it would be "semantically incorrect" to require(-dev) the standard, but "semantically correct" to use the provide key.

https://getcomposer.org/doc/04-schema.md#provide

Not sure how one could query the Packagist API on that, though...

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.

A small idea I have would be allow for some sort of an optional .skeleton.php file that would make it possible to redefine the structure. Could look something like this:

return new class implements SkeletonInterface
{
     public function sourceDirectory()
     {
          return '/src';
     }, //...
}

You get the idea. This would make it possible for projects with existing structure that they can't just change to still make the directory mapping known to some components that need it.

For example bower allows specifying main files in the bower.json instead of relying on a predefined component structure.

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?

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.

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.

In the days of Git, it seems generally redundant to manually include a detailed changelog file in a package, as the changelog can easily be viewed by either running git log, or checking the project in its source repo, be it github, gitlab, bbcloud or other.

On the other hand, I find extremely valuable the presence of a hand-curated NEWS file, which highlights the most important user-visible changes for each release.
It is true that many well-behaved packages do add release notes in their repo of choice, but having the complete list of changes available locally, for all releases, does add extra value.

(See https://www.gnu.org/prep/standards/standards.html#NEWS-File for a description of what should go into NEWS, and as an example of why that file name is already a well known standard and not my personal invention).

Given the above, why not recommending usage of NEWS instead of CHANGELOG?

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.

This is a really great project. I like this standard, because it fits to my personal experience und taste.
Is this standard only for "Root-Level Directories"? What about the public assets?

Example 1

public/js/              # java-script files
public/css/             # css files
public/images/          # image files
public/fonts/           # font files
public/icons/           # icon files

Example 2 (like Bootstrap)

public/assets/js/       # java-script files
public/assets/css/      # css files
public/assets/img/      # image files
public/assets/fonts/    # font files
public/assets/ico/      # icon files

When developing with GitHub based package repositories a common location of the CONTRIBUTING file is .github/CONTRIBUTING.

Normally i tend to use "assets" otherelse than "resources" because in some of the projects i've been, some of the teams get confused about what the "resources" folder is, for some is for the styling stuff like css or sass or images only and others think is for packages like vendor, there's a way for better standard for naming this folder?

Seems validation and generating would be very simple if use docker image. Would you publish image if i contribute Dockerfile?

It SHOULD be dead easy for contributors and maintainers to run tests, fix coding standard violations, and do new releases (obvs. maintainers only).

It's RECOMMENDED to provide these via Composer scripts where suitable and feasible.

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.

@pmjones similar to the resources folder (#12), I often have an examples folder in my packages.

I'm aware that this is kind of documentation but since I want to make it easy for people, which are checking out my libararies, I often include easy to find and easy to execute example scripts in the root folder under examples.

It seems I am not the only one:

• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L16
  examples/ 1748
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L40
  example/ 698
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L316
  Example/ 31
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L322
  Examples/ 31
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L860
  _examples/ 6
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L953
  code-examples/ 5
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L1664
  _example/ 2
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L2130
  example-scripts/ 2
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L2288
  example code/ 2

But I guess this folder is not as important as the other ones, so it could be included as a recommendation instead?

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?

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?

Hey, it seems the Packagist state is out of date, the last commit it knows about is 8e9ed29 :)

I come up with a question to you. Maybe you have some tips or recommendations?

I was starting a package with a concrete PHP package skeleton based on your PDS Skeleton:
https://github.com/tbreuss/php-package-skeleton

The idea is to have some kind of a boilerplate that enables you to quickly start a new project. In contrast to PDS it contains concrete implementations.

What do you think about this?

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 like that this project is codifying what is being observed in the eco-system rather than documenting an idea and trying to get people to buy into it.

Have the team considered submitting this for consideration as a PSR for libraries?

Please clarify the difference between /public and /src.

A common setup is to use one index.php file to route requests to other parts of the project. Please address this setup specifically in the documentation.

• LGPL is a two-part license (the GPL plus the lesser extensions). However, these naïve rules assume the license must be a single file.
• According to the GNU how-to the license should be named COPYING but these ignorant rules state it must be named LICENSE.
• GitHub's license-detection software does not support the LGPL being specified in a file named anything other than COPYING.LESSER. These arbitrary rules state the extension should be lower-case and only used to indicate file format.

In light of these poorly-researched rules you should not be making rules about licenses at all. That is, rather than attempting to make amends, simply remove any rules regarding licensing because you cannot construct such rules in a useful manner, particularly when you spare no effort to research the subject.

This one might be tad controversial, but hey we're shaping a standard. Directories like bin and config should be also be pluralised like docs or tests.

Add a compliant skeleton generator. It should not assume that the directory structure is empty.

Running pds-skeleton generate <dirpath> does not check the correct directory file existence, unlike pds-skeleton validate <dirpath> which does. It's a simple bug from a missing argument. PR coming momentarily.

Are you planning a badges/shields service for packages which complies with the Standard PHP package skeleton?

https://github.com/badges/shields

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 seems to be common place among many PHP applications to have a standard /data directory. Since I do not see it in the skeleton, and some of the linked research examples, I assume it was discussed and eliminated from consideration. Thoughts?