php-pds / skeleton Goto Github PK
View Code? Open in Web Editor NEWStandard PHP package skeleton.
License: Creative Commons Attribution Share Alike 4.0 International
Standard PHP package skeleton.
License: Creative Commons Attribution Share Alike 4.0 International
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 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?
Are you planning a badges/shields service for packages which complies with the Standard PHP package skeleton?
Hey, it seems the Packagist state is out of date, the last commit it knows about is 8e9ed29 :)
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
Add a compliant skeleton generator. It should not assume that the directory structure is empty.
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:
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.
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.)
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:
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?
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)
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?
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.
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
.
Perhaps the discussion on /src should prescribe that a PSR-4 autoloader should be used.
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
.
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.
@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:
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 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.
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, thevendor/
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, thevendor/
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 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...
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
I think we should change these terms:
resources -> res (like bin, config, doc, etc...)
tests -> test
docs -> doc
Like most of languages...
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
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.
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?
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?
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?
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/
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.
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?
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.
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.
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
.
When developing with GitHub based package repositories a common location of the CONTRIBUTING
file is .github/CONTRIBUTING
.
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.
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.
Seems validation and generating would be very simple if use docker image. Would you publish image if i contribute Dockerfile?
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.
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.
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:
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.
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 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?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.