Document how to install ClassicPress using composer

[nylen]

We support installing ClassicPress via composer as of ClassicPress/ClassicPress#169, thanks @pierre-dargham!

Now we need to document it at https://docs.classicpress.net/installing-classicpress/. We can start with how to install the nightly build, and after beta1 is released we'll put an official package up on packagist.

Here's an example of what needs to happen to make this work: https://github.com/globalis-ms/wp-cubi/commit/fc45fac34424b3af43f8f98d0a6004e149bf6150

We should turn this into a minimal composer.json file and a set of steps / commands to make it work, ideally including making the composer.json file inaccessible from the web server.

See also: ClassicPress/ClassicPress-v1#239

[nylen]

Assigning @striebwj to help with this per Slack conversation.

[pierre-dargham]

Thank you for opening the issue, I totally agreed that we need to provide some basic documentation here. I'll try to come back to this issue and give you my thoughts asap

[pierre-dargham]

Hello @nylen (cc @striebwj and @johnpbloch )

I've made an example repository to show the very minimal structure needed to start a ClassicPress project with composer : https://github.com/pierre-dargham/classicpress-composer-boilerplate

The README.md provides the steps to complete the install.

I'm not sure I'll have enough time during next weeks to really contribute to the documentation, but I hope this small contribution could give you the general idea.

Based on this example, we could eventually setup a proper classicpress/classicpress-composer-boilerplate repository and package in the future, and make it the official example / boilerplate.

ideally including making the composer.json file inaccessible from the web server.

Regarding that : it's not a composer install specific problem, because for now, we'll have this file in classic installs too. First step could be to include a How to deploy ClassicPress section in the general documentation, that recommends to not deploy this file, and other files like readme.html, licence.txt ... Second step could be to check if adding composer.json export-ignore in the build .gitattributes file works (it could be enough to exclude the file from the github builds zip archives, it needs to be checked)

[nylen]

This is started:

• https://docs.classicpress.net/installing-classicpress/#installing-with-composer
• https://docs.classicpress.net/installing-classicpress/installing-with-composer/

If anyone has any further feedback on this documentation (@pierre-dargham or @johnpbloch especially), that would be great.

I'll leave this open because we need to update that page with instructions once 1.0.0-beta1 is released and made available on packagist.

[pierre-dargham]

Hi @nylen !

A little feedback here :

Notes :

• composer.json : "minimum-stability" :"dev", is needed only because we don't have a first stable version (1.0.0) for now
• composer.json : declaring repository https://github.com/ClassyBot/ClassicPress-nightly.git is needed only if you want to install the nightly builds. Once we have created the packagist.org package, we don't need it in the standard install process
• composer.json : declaring repository https://wpackagist.org is needed only if you want to require wordpress.org plugins / themes

Issues :

• The steps you give does not provide the minimal required structure. We need a copy of wp-config.php and index.php (with a few modifications) outside the WordPress core directory, so they are not overridden on composer updates, and in order to correct some paths : handle the core being in it's own directory and not at the project root, and handle having the wp-content directory elsewhere (because we can not put our plugins and themes in the WordPress core directory for the same reason : they would be overridden on composer updates).

• Here are the modified lines needed on the copied wp-config.php and index.php : https://github.com/pierre-dargham/classicpress-composer-boilerplate/blob/master/index.php#L17 , https://github.com/pierre-dargham/classicpress-composer-boilerplate/blob/master/wp-config.php#L40:L48 and https://github.com/pierre-dargham/classicpress-composer-boilerplate/blob/master/wp-config.php#L96

• We need to define the paths for composer installs on https://github.com/pierre-dargham/classicpress-composer-boilerplate/blob/master/composer.json#L21:L25

I really tried to put the very strict minimal structure into my example on https://github.com/pierre-dargham/classicpress-composer-boilerplate The only optional thing I did was requiring wpackagist-theme/twentyseventeen, but I thought it was better to have a non-broken frontend at the end of the install, so I stayed with the last default theme.

[nylen]

1.0.0-beta1 is released on Packagist: https://packagist.org/packages/classicpress/classicpress

Related to notes on Composer file structure: https://github.com/ClassicPress/ClassicPress/pull/242#issuecomment-440145245 cc @mikeschinkel

[pierre-dargham]

Thank you @nylen !

I'll try to come back to it tomorrow, run some tests, check the related discussion https://github.com/ClassicPress/ClassicPress/pull/242 and update https://github.com/pierre-dargham/classicpress-composer-boilerplate to use the official release packages, instead of the nighty builds.

[nylen]

I've also updated the documentation page. I'll leave this issue open because there is still more left to document here:

NOTE: We are still working on this guide, and there is a lot that is not covered yet – most importantly, turning a ClassicPress package installed this way into a working site!

[nylen]

A couple of WP-related guides that may be helpful here:

• https://roots.io/using-composer-with-wordpress/
• https://composer.rarst.net/

[pierre-dargham]

I've run some checks, new release package is working fine ! I've also updated https://github.com/pierre-dargham/classicpress-composer-boilerplate and its documentation

[knowler]

Since Bedrock (roots/bedrock) already has a working Composer setup + disables automatic updates, swapping WordPress out for ClassicPress is as easy as changing:

+   "classicpress/classicpress": "1.0.0-beta1",
-   "johnpbloch/wordpress": "4.9.8",

Then running composer update.

Full composer.json: https://gist.github.com/knowler/ef1028834beeb2aaa1b4fa9869751cd7

I don’t like the side effects of setting minimum-stability to beta or dev since plugin/theme/dependency installs can start using unstable versions, I'd prefer to see a specific version set — even if it is beta. Recommending people to change the minimum-stability could cause issues for them now and down the line after the 1.0.0 release if they forget to remove the constraint.

Also, maybe it's worth mentioning in the documentation that working Composer WordPress installations like Bedrock should work seamlessly with ClassicPress.

[knowler]

Alternatively, use: "classicpress/classicpress": "@beta" or "1.0.*@beta".

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

[nylen]

A bit late on addressing feedback here, but I've made the following changes to this documentation page:

• No more minimum-stability - use an @beta version specifier for ClassicPress only.
• Explain a bit more about what's needed after installation, along with links to this thread and to Bedrock: https://docs.classicpress.net/installing-classicpress/installing-with-composer/#after-installation
• Add a short "Migrating from WordPress" section as described above: https://docs.classicpress.net/installing-classicpress/installing-with-composer/#migrating-from-wordpress

If you have further suggestions for improvement, feel free to let me know here on this issue, in Slack, or on our documentation subforum.