Permalink
Browse files

feature(composer): Fully support installing Elgg as a composer depend…

…ency

Can register views, translations, and start.php from the root dir now

I left out "classes" intentionally to encourage composer autoloader usage.

Fixes #8431
  • Loading branch information...
ewinslow committed Jun 8, 2015
1 parent 6fa8092 commit fceafea600b1b7067dd19cc005352b04a7921d65
Showing with 681 additions and 608 deletions.
  1. +1 −0 .gitignore
  2. +1 −1 autoloader.php
  3. +1 −1 docs/admin/backup-restore.rst
  4. +34 −10 docs/guides/dont-modify-core.rst
  5. +3 −1 docs/guides/guidelines.rst
  6. +58 −11 docs/guides/upgrading.rst
  7. +12 −10 docs/intro/install.rst
  8. +27 −48 docs/tutorials/blog.rst
  9. +14 −63 docs/tutorials/hello_world.rst
  10. BIN docs/tutorials/images/hello_world1.png
  11. BIN docs/tutorials/images/hello_world2.png
  12. +4 −4 docs/tutorials/index.rst
  13. +4 −29 docs/tutorials/indexpage.rst
  14. +4 −25 docs/tutorials/widget.rst
  15. +6 −13 docs/tutorials/wysiwyg.rst
  16. +2 −7 engine/classes/Elgg/ActionsService.php
  17. +172 −34 engine/classes/Elgg/Application.php
  18. +44 −27 engine/classes/Elgg/Cache/SimpleCache.php
  19. +42 −0 engine/classes/Elgg/Composer/PostUpdate.php
  20. +4 −8 engine/classes/Elgg/Config.php
  21. +1 −2 engine/classes/Elgg/Di/ServiceProvider.php
  22. +12 −0 engine/classes/Elgg/Filesystem/Directory.php
  23. +5 −13 engine/classes/Elgg/Filesystem/Directory/Fly.php
  24. +24 −0 engine/classes/Elgg/Filesystem/Directory/Local.php
  25. +7 −0 engine/classes/Elgg/Filesystem/File.php
  26. +17 −1 engine/classes/Elgg/I18n/Translator.php
  27. +0 −7 engine/classes/Elgg/Services/Config.php
  28. +5 −5 engine/classes/Elgg/ViewsService.php
  29. +49 −48 engine/classes/ElggInstaller.php
  30. +1 −15 engine/classes/ElggPlugin.php
  31. +12 −10 engine/classes/ElggRewriteTester.php
  32. +26 −12 engine/lib/configuration.php
  33. +10 −11 engine/lib/elgglib.php
  34. +3 −3 engine/lib/plugins.php
  35. +1 −1 engine/lib/upgrade.php
  36. +2 −1 engine/lib/views.php
  37. +3 −3 engine/start.php
  38. +1 −1 engine/tests/phpunit/bootstrap.php
  39. +1 −4 engine/tests/suite.php
  40. +6 −11 index.php
  41. +5 −16 install.php
  42. +1 −3 install/cli/sample_installer.php
  43. +5 −6 install/cli/travis_installer.php
  44. +2 −0 install/config/htaccess.dist
  45. +3 −2 mod/file/download.php
  46. +3 −3 mod/file/thumbnail.php
  47. +2 −1 mod/profile/icondirect.php
  48. +5 −90 upgrade.php
  49. +21 −21 views/default/elgg.js.php
  50. +1 −1 views/default/elgg/admin.js
  51. +1 −1 views/default/lightbox.js.php
  52. +13 −8 views/installation/page/default.php
  53. +0 −10 views/installation/page/elements/footer.php
  54. +0 −6 views/installation/page/elements/header.php
View
@@ -1,5 +1,6 @@
# ignore Elgg configuration
/engine/settings.php
/settings.php
/.htaccess
/mod/*
/composer.lock
View
@@ -31,4 +31,4 @@
echo "You must set up the project dependencies. Run the following commands:\n" .
"curl -s http://getcomposer.org/installer | php\n" .
"php composer.phar install";
exit;
exit;
@@ -206,7 +206,7 @@ Bringing it all together
The restored elgg installation knows **nothing** about the new database name, database username, directory structure, etc. That's what we're going to address here.
Edit ``/public_html/engine/settings.php`` on the new hosting provider to reflect the database information for the database that you just created.
Edit ``/public_html/settings.php`` on the new hosting provider to reflect the database information for the database that you just created.
.. code:: php
@@ -3,34 +3,58 @@ Don't Modify Core
.. warning::
Don't modify any non-config files that come with Elgg.
In general, you shouldn't modify non-config files that come with third-party software like Elgg.
Instead, create a :doc:`custom plugin<plugins>` and alter behavior through the rich Elgg plugin API.
The best way to customize the behavior of Elgg is to :doc:`install Elgg as a composer dependency</intro/install>`
and use the root directory to store modifications specific to your application,
and alter behavior through the rich Elgg plugin API.
Here are the main reasons not to modify the core of Elgg, or of any other third party software that offers better extensibility routes through plugins.
If you'd like to share customizations between sites or even publish your changes
as a reusable package for the community, create a :doc:`plugin<plugins>`
using the same plugin APIs and file structure.
It makes it hard to get help
----------------------------
When you don't share the same codebase as everyone else, it's impossible for others to know what is going on in your system and whether your changes are to blame. This can frustrate those who offer help because it can add considerable noise to the support process.
When you don't share the same codebase as everyone else,
it's impossible for others to know what is going on in your system
and whether your changes are to blame. This can frustrate those who offer help
because it can add considerable noise to the support process.
It makes upgrading tricky and potentially disastrous
----------------------------------------------------
You will certainly want or need to upgrade Elgg to take advantage of security patches, new features, new plugin APIs, new stability and performance improvements. If you've modified core files, then you must be very careful when upgrading that your changes are not overwritten and that they are compatible with the new Elgg code. If your changes are lost or incompatible, then the upgrade may remove features you've added or even completely break your site.
You will certainly want or need to upgrade Elgg to take advantage of
This can also be a slippery slope. Lots of modifications can lead you to an upgrade process so complex that it's practically impossible. There are lots of sites stuck running old versions software due to taking this path.
* security patches
* new features
* new plugin APIs
* new stability improvements
* performance improvements
If you've modified core files, then you must be very careful when upgrading that
your changes are not overwritten and that they are compatible with the new Elgg code.
If your changes are lost or incompatible, then the upgrade may remove features
you've added and even completely break your site.
This can also be a slippery slope. Lots of modifications can lead you to an
upgrade process so complex that it's practically impossible.
There are lots of sites stuck running old versions software due to taking this path.
It may break plugins
--------------------
You may not realize until much later that your "quick fix" broke seemingly unrelated functionality that plugins depended on.
You may not realize until much later that your "quick fix" broke
seemingly unrelated functionality that plugins depended on.
Summary
-------
- Resist the temptation
Editing existing files is quick and easy, but doing so heavily risks the maintainability, security, and stability of your site.
- When receiving advice, consider if the person telling you to modify core will be around to rescue you if you run into trouble later!
Editing existing files is quick and easy, but doing so heavily risks the
maintainability, security, and stability of your site.
- When receiving advice, consider if the person telling you to modify core will
be around to rescue you if you run into trouble later!
- Apply these principle to software in general.
If you can avoid it, don't modify third party plugins either, for many of the same reasons: Plugin authors release new versions, too, and you will want those updates.
If you can avoid it, don't modify third party plugins either, for the same reasons:
Plugin authors release new versions, too, and you will want those updates.
@@ -1,7 +1,9 @@
Plugin coding guidelines
========================
In addition to the Elgg Coding Standards, these are guidelines for creating plugins. Core plugins are being updated to this format and all plugin authors should follow these guidelines in their own plugins.
In addition to the Elgg Coding Standards, these are guidelines for creating plugins.
Core plugins are being updated to this format and all plugin authors should follow
these guidelines in their own plugins.
.. seealso::
View
@@ -12,6 +12,64 @@ See the administrator guides for :doc:`how to upgrade a live site </admin/upgrad
From 1.x to 2.0
===============
Elgg can be now installed as a composer dependency instead of at document root
------------------------------------------------------------------------------
That means an Elgg site can look something like this:
.. code::
settings.php
vendor/
elgg/
elgg/
engine/
start.php
_graphics/
elgg_sprites.png
mod/
blog
bookmarks
...
``elgg_get_root_path`` and ``$CONFIG->path`` will return the path to the application
root directory (the one containing ``settings.php``), which is not necessarily the
same as Elgg core's root directory (which in this case is ``vendor/elgg/elgg/``).
Do not attempt to access the core Elgg from your plugin directly, since you cannot
rely on its location on the filesystem.
In particular, don't try load ``engine/start.php``.
.. code:: php
// Don't do this!
dirname(__DIR__) . "/engine/start.php";
To boot Elgg manually, you can use the class ``Elgg\Application``.
.. code:: php
// boot Elgg in mod/myplugin/foo.php
require_once dirname(dirname(__DIR__)) . '/vendor/autoload.php';
\Elgg\Application::start();
However, use this approach sparingly. Prefer :doc:`routing` instead whenever possible
as that keeps your public URLs and your filesystem layout decoupled.
Also, don't try to access the ``_graphics`` files directly.
.. code:: php
readfile(elgg_get_root_path() . "_graphics/elgg_sprites.png");
Use :doc:`views` instead:
.. code:: php
echo elgg_view('elgg_sprites.png');
Cacheable views must have a file extension in their names
---------------------------------------------------------
@@ -29,7 +87,6 @@ which can result in conflicts between cacheable views that don't have file exten
to disambiguate files from directories.
Dropped ``jquery-migrate`` and upgraded ``jquery`` to ^2.1.4
------------------------------------------------------------
@@ -284,16 +341,6 @@ If your code uses one of the following functions, read below.
If you provide a callable ``$handler`` to be called with the results, your handler will now receive a
``\Doctrine\DBAL\Driver\Statement`` object. Formerly this was an ext/mysql ``result`` resource.
engine/start.php is deprecated
------------------------------
Plugins should use the class ``Elgg\Application`` to boot Elgg. Typical usage:
.. code:: php
// boot Elgg in mod/myplugin/foo.php
require_once dirname(dirname(__DIR__)) . '/autoloader.php';
(new \Elgg\Application)->bootCore();
Event/Hook calling order may change
-----------------------------------
View
@@ -69,20 +69,23 @@ Overview
Upload Elgg
-----------
- Download the `latest version of Elgg`_
- Upload the ZIP file with an FTP client to your server
- Unzip the files in your domain's document root (/home/username/www).
.. _latest version of Elgg: http://elgg.org/download.php
Elgg also supports installing from source with Composer:
With Composer (recommended if comfortable with CLI):
.. code:: shell
cd /path/to/wwwroot/
composer self-update
composer global require "fxp/composer-asset-plugin:~1.0"
composer create-project Elgg/Elgg:~2.0 .
composer create-project elgg/starter-project:dev-master .
From pre-packaged zip (recommended if not comfortable with CLI):
- Download the `latest version of Elgg`_
- Upload the ZIP file with an FTP client to your server
- Unzip the files in your domain's document root.
.. _latest version of Elgg: https://elgg.org/download.php
Create a data folder
--------------------
@@ -145,8 +148,7 @@ A note on settings.php and .htaccess
The Elgg installer will try to create two files for you:
- engine/settings.php, which contains the database settings for your
installation
- settings.php, which contains local environment configuration for your installation
- .htaccess, which allows Elgg to generate dynamic URLs
If these files can't be automatically generated, for example because the
Oops, something went wrong.

0 comments on commit fceafea

Please sign in to comment.