abtercms/abterphp

PHP implementation of AbterCMS based on the Opulence framework

dev-main 2022-06-12 16:37 UTC

Requires

• abterphp/admin: *
• abterphp/bootstrap4-website: *
• abterphp/contact: *
• abterphp/docmed: *
• abterphp/files: *
• abterphp/framework: *
• abterphp/propeller-admin: *
• abterphp/website: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.18
• phan/phan: ^4.0
• phpmd/phpmd: ^2.9
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3.5

Suggests

• ext-redis: Allows better caching

MIT

• Peter Aba

README

AbterPHP is the first and currently the only implementation of AbterCMS, providing backend, frontend and a REST API for it. It does not require much JavaScript knowledge as it uses jQuery instead of some nodejs based solution, therefore many might find it easier to learn, maintain or deploy.

It is based on the excellent Opulence framework.

Why another CMS?

The system has 3 reasons to exist:

1. Provide an easily accessible alternative to anyone who needs a truly simple website.
2. Educational purposes.
3. Provide a reasonably solid base for dev-shops that have PHP resources now, but want to keep their tech stack open for change.

You'll find more information on design decisions on the website.

AbterCMS

AbterCMS is a polyglot CMS system which is meant to provide both easily customizable, maintainable and deployable website solutions for simple use cases, and also a solid base for startups iterating over ideas fast.

It is planned that there will be at least a Go API and some nodejs based backend and frontend solution. (Elm, Vue or React most likely.)

Status

AbterPHP backend and frontend are almost feature complete, but the API is not stable, not complete and not properly tested yet. The code coverage is already quite good, around 95% overall. Documentation is at very early stages. Therefore the current status is Pre-alpha.

Module	Github Actions Build Status	Scrutinizer Code Quality	Scrutinizer Build Status	Coverage Status
Framework
Admin
Website
Contact
Files
Bootstrap4Website
PropellerAdmin

Installation

Development

Pre-requisite: Grab the source code

This should be fairly obvious if you're reading it, but feel free to download the code from Github or clone the repository. Just use the "Clone or download" button to get you started.

Pre-requisite: Install docker

The recommended way of getting started with the AbterPHP is via docker. While it is not necessarily mandatory, some of the documentation might assume that all developers use docker for development. If you want to run the code, you'll have to ensure that you have the right version of PHP, with the neccessary modules and that you have at least a supported version of MySQL (or later PostgreSQL). While having Redis or Memcached is great, those are not mandatory.

Pre-requisite: Install mkcert

Since security is a top priority, pure http is not supported out of the box, therefore you'll need to install a certificate. The recommended way is using mkcert. While it is not necessarily mandatory, some of the documentation might assume that all developers use mkcert for development.

Pre-requisite: Open the project in a console

The rest of the installation documentation will assume that . is the root directory of the project.

Pre-requisite: Fetch submodules

To make sure you can use docker as your development platform, you should make sure to have all the configs associated.

git submodule update --init --recursive

Later, to update the submodules, use the following git command:

git submodule update --remote

Pre-requisite: Add abtercms.test as localhost in /etc/hosts on Linux and OSX or ??? on Windows.

# /etc/hosts
# [...]
127.0.0.1	abtercms.test

Create certificate

Since security is a top priority, you'll need to create a certificate and move it into docker/nginx/certs/

mkcert abtercms.test "*.abtercms.test"
mv abtercms.test+1* ./docker/nginx/certs/

Set some permissions

chmod -R 0777 ./tmp ./public/tmp
chmod +x apex

Spin up the containers

docker-compose pull
docker-compose up -d

Install the dependencies

To install dependencies, we recommend running make from inside the PHP container:

docker-compose exec cli make

Ensure your settings are sane

Although we try to provide a reasonable set of settings for getting started quickly, at this point you may want to edit config/environment/.env.app.php to make your settings sane for your needs. Please note however that these values can be and in some cases will be overwritten by your environment variables. This means that if you are running the system with docker-compose than you might need to edit some of these values in docker-compose.yml.

If you do not have the file config/environment/.env.app.php then something must have gone wrong in the previous step, because it should be created during php composer.phar install.

More documentation on the settings will be written later.

Install the db schema and create a new admin user

You need to log into the PHP container (again) run migrations and create a user.

Note: That AbterPHP uses zxcvbn-php to verify password strength. This is a modern library that does not enforce rules like using numbers and smaller and upper case characters nor does it simply count characters. E.g ryvenglotbutnofasewordpass is a strong password, but verylongbutnotsafepassword is not. (To help migrating users from other systems, it is possible to create users using weak password with the --unsafe argument.)

docker-compose exec php sh
> ./apex migrations:up
> ./apex user:create {username} {email} {strongPassword} admin en
> exit

If everything went well, you should be able to log in with your new user at https://abtercms.test/login-iddqd, given that you haven't yet changed your ADMIN_LOGIN_PATH environment variable in config/environment/.env.app.php.

Production

Since AbterPHP is in Early Preview state, you probably shouldn't deploy it to production at the moment.

Stack

AbterPHP is based on Opulence, but uses a few more projects alongside Opulence:

• Monolog for logging
• Whoops for error reporting in non-production environments
• Flysystem for handling filesystem (incomplete implementation)
• Casbin for authorization
• Minify for minifying assets (Website module)
• Swiftmailer for sending emails (Contact module)
• Slugify for creating web-safe identifiers (Admin module)
• jQuery for most of the JavaScript in place (Admin module)
• js-sha3 for browser-side encryption (Admin module)
• Trumbowyg as a wysiwyg solution (Admin module)
• zxcvbn from Dropbox for password strength estimations (Admin module)
• zxcvbn-php PHP version of zxcvbn (Admin module)
• OAuth 2.0 Server for API authentication and authorization with Nyholm/psr7 as PSR-7 request / response library.

If you want to contribute code you'll also need to get familiar with these tools:

• PhpUnit for unit tests
• vfsStream for mocking the filesystem
• PHP_CodeSniffer for code formatting
• PHPMD - PHP Mess Detector for code quality

AbterPHP currently only supports MySQL as the database system, although PostgreSQL support is very likely to happen before the first stable version.

Roadmap

First alpha musts:

1. Make the frontend framework decoupled from the backend system
2. Use ILogger instead of Logger
3. More fine grained authorization
   • ACL implemented for pages
   • Advanced settings access role for pages
   • Multiple user group for one user
   • New user roles: file uploader, layout designer, page writer
4. Modular asset management
5. Completed test automation and automatic reviews set up
6. Refactored module manager
7. Ensured that user creation enforces good passwords in CLI.
8. Uuid ids
9. Removed $value in Select constructor
10. Switch $attribute and $tag order
11. 1 nice website module
12. Page category
13. Re-add navigation item filtering by enforcer
14. Fix grids:
    • Filter labels
    • Page size selections
    • Sorting
    • Hide IDs
15. Separate grid and form assets in admin
16. API keys for users
17. Fix forms:
    • "Red" / "Danger" Back to list buttons
    • Create and new button
18. Initial API defined and published
19. Documentation page exists
20. All implemented API endpoints return properly formatted errors
21. Optionally embed file content into getFile API endpoint
22. Disable block cache for development
23. List pages on frontend by category (simple)
24. List pages on frontend by category (detailed)
25. Upgrade to phpunit 8.4
26. 70%+ of PHP source code unit tested, except for bootstrappers and console commands
27. Tested project on OSX
28. Fix file uploads
29. File category identifiers
30. File category public/private
31. Page structure name
32. Fix page publication
33. Login errors displayed
34. Fix filters
35. Verified that localhost_router.php works as expected or remove it if too hard to fix
36. API verified against Zalando REST API recommendations
37. Tested project on Windows 10+

First beta musts:

1. Existing phpmd ignore cases reviewed
2. Client creation via CLI
3. Optionally embed rendered page body parameter
4. 1st nice website module
5. Must-accept-cookie module
6. 2nd nice website module
7. 3rd nice website module
8. API implemented
9. 1 grid is covered with acceptance tests (filters, pagination included)
10. 1 form is covered with acceptance tests (displaying with new and existing entity and saving included)
11. Highlight form fields with validation errors
12. 12-factor compliance reviewed and improvements planned
13. Reviewed and refactored global $abterModuleManager usage
14. Test loading entities that don't exist or faulty
15. Fix empty exceptions (\LogicException, \RuntimeException, \InvalidArgumentException)
16. Ensure identifiers do not contain a comma (explode issue)
17. 70%+ of JS source code unit tested
18. Enable Generic.Commenting.DocComment phpcs rules
19. Improve validation
    • Review validation factories
    • Create new validation rules where needed
20. Cached translations
21. Documentation covers getting started and main design goals
22. Fix sidebar propeller "bug"
23. Cache navigation for user
24. Enable/Disable modules from console
25. Setup wizard (admin user + security settings)
26. Revoke token endpoint
27. Scope checks during serving API calls
28. RSS feeds
29. Default image for pages
30. Improved security implementing related headers as recommended:
    • https://medium.freecodecamp.org/secure-your-web-application-with-these-http-headers-fd66e0367628
    • https://medium.freecodecamp.org/web-security-hardening-http-cookies-be8d8d8016e1
31. Logs don't have to be local files
32. Page should use Layout as entity -> Fix getGridQuery::PageSqlDataMapper

1.0 musts:

1. API designed finalized (community input?)
2. API test complete
3. Acceptance tests for main use cases of each module
4. All grids, paginations, filters covered with acceptance tests
5. Displaying and saving of all forms and proper returns covered with acceptance tests
6. Refactored helpers
7. AbterPhp\Framework\Form\Factory\Base::getMultiSelectSize -> move to helper or Select
8. Refactored configs
9. Refactored bootstrappers (again)
   • Use Config Provider to remove bootstrappers
   • Validators registered in framework
10. All constants reviewed
11. Documentation "complete"
12. 12-factor compliance clearly stated
13. More useful dashboard (community input?)
14. Enable ONLY_FULL_GROUP_BY in mysql.conf
15. Refactor
    • AbterPhp\Framework\Html\Collection
    • AbterPhp\Framework\Html\Helper\ArrayHelper::formatAttribute
    • Classes with CouplingBetweenObjects over a 15-20 (TBD)
    • AbterPhp\Framework\Module\Manager
16. Proper maintenance handling
17. Consider caching processed module data

Ideas

Ideas for 1.0:

• Smoke tests with data generators
• PostgreSQL support
• Forgotten password feature
• 2FA feature
  • https://www.neonwiz.com/blog/two-factor-authentication-2fa-in-php/
  • https://github.com/RobThree/TwoFactorAuth
  • https://www.idontplaydarts.com/2011/07/google-totp-two-factor-authentication-for-php/
  • https://medium.com/@richb_/easy-two-factor-authentication-2fa-with-google-authenticator-php-108388a1ea23
  • https://medium.com/s/the-firewall/episode-3-multifactor-authentication-b25e9e1d2c18
• Serverless support
  • S3 usage as filesystem?
• Contact form table holding contact details
• Simple blog module
• Pick new frontend framework for backend system and implement it
• Actions to extend Cell
• binary(16) ids instead of char(36)
  • Needs MySQL 8.0 BIN_TO_UUID and UUID_TO_BIN support
  • Needs query builder support (although not a must)
• Setup codeclimate.com properly
• Ask about discarding changes when using the Back to List button
• Icons for Grid and Form buttons
• Website entity to support multipage setups
• Frontend language selection

Ideas for 1.1:

• WYSIWYG file selector
• WYSIWYG image upload
• User image upload
• Cleanup HTML templates
• Protected pages (Pages only accessible logged in)

Long tail:

• Opulence authorization (instead of or on top of Casbin)