A web application for creating paragraph games and visual novels.
Table of contents generated with markdown-toc. Thank you.
This repository is licensed under the BSD 2-Clause License, allowing source code usage and modification under the terms described in LICENSE.md.
However, all binary builds (Windows, Android, iOS, macOS and Linux applications) or on-line version available at MagiEdit or Niner Games’ websites are proprietary. Redistribution, modification, or resale of these without explicit permission is not allowed.
❤️ You’re welcome to explore, learn from, and reuse the code in this repo. But on-line version and published builds are a commercial product—please respect that distinction. Thank you. ❤️
The following components are required and must be installed:
-
Local LAMP web server, e.g.: XAMPP equipped with a PHP interpreter in at least version 8.2.0.
-
Dependency manager Composer.
-
Modern web browser, e.g. Firefox, Edge, Chrome, Safari (preferably -- in the latest version).
The application has been tested only in Windows 11 Pro, under the control of the XAMPP server and the PHP 8.2.4 interpreter.
If XAMPP (or another LAMP-type package) is not installed, you can download it from ApacheFriends.org.
If you do not have Git for Windows, you can download it from this page.
If you don't have Composer, you can install it using this guide.
Clone the main repository to a folder of your choice on your local disk:
git clone git@github.com:niner-games/magiedit.web.gitUpdate all components:
cd magiedit.web
composer updateThe -ignore-platform-req=php flag should only be used if you have PHP version 8.2 or later.
Initialize the production environment:
php init --env=Production --overwrite=All --delete=AllIf you want to use a root folder other than the default one, you need to configure it.
Start the web server and the MySQL / MariaDB database server.
If you are using Windows, make sure that your web server is always started with administrator privileges.
This is especially important in development and test environments. Without this, the application will not be able to read the git commit hash and git tag number. And it may show an incorrect or empty version of the application.
Navigate to the folder where the application is installed in your web browser. Double check that your environment meets the minimum requirements:
http://localhost/niner-games/magiedit.web/requirements.php
Check all errors and warnings carefully. Before continuing, resolve any issues that you can resolve.
Open the configuration file common/config/main-local.php and provide the name of the current environment, for example:
putenv('ENVIRONMENT_NAME=prod');This is for informational reasons only (added to application version in the footer), but it is important to provide it.
You can use any name instead of prod. For example: dev, test, pre-prod, uat, backup etc.
Open the configuration file frontend/config/main-local.php, find recaptcha component in components section and provide
your own pair of site key and secret that are needed for this application to work.
'recaptcha' => [
'class' => 'recaptcha\ReCaptchaComponent',
'siteKey' => 'your-dev-or-prod-site-key',
'secretKey' => 'your-dev-or-prod-secret-key',
],You can generate new pair at Google reCAPTCHA admin site. For more information visit Google reCAPTCHA FAQ. For security reasons, always use separate pair and never re-use any pair in any environment or application!
When generating key for DEV or TEST environments, include "localhost" and "127.0.0.1" domains in key settings. If you are generating a pair for production purposes, include an actual domain (i.e. "magiedit.com") in key settings.
If you have initialized application in production mode then there's an extra .htaccess file generated in the
root folder to make sure that this root folder (i.e. domain) correctly points to /frontend/web folder, which is (or should
be) the only web-accessible folder in the entire application. You may want to check, if settings is this file does not break
your server's configuration.
In addition, there's a baseUrl property of request and urlManager components, nullified to empty string ('') in
fronted/config/main-local.php. It is made so for the same reasons as above. You may want to check and possibly change
that file as well.
Create the database manually (using the software of your choice) or by executing the following SQL command:
CREATE DATABASE magiedit;Create a separate user with at least SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER,
INDEX and DROP privileges for this database:
CREATE USER 'scripts'@'localhost' IDENTIFIED VIA mysql_native_password USING 'P#gtitO@D:=~5C.7?IDyF1?dZ2Yo|*'; GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON *.* TO 'scripts'@'localhost' REQUIRE NONE WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 MAX_USER_CONNECTIONS 0;(change password 'P#gtitO@D:=~5C.7?IDyF1?dZ2Yo|* to different one in above command)
Open file common/config/main-local.php and provide correct database server configuration, for example:
$dbScheme = 'mysql';
$dbHost = 'localhost';
$dbName = 'magiedit';
$dbUsername = 'scripts';
$dbPassword = 'P#gtitO@D:=~5C.7?IDyF1?dZ2Yo|*';
$dbCharset = 'utf8';(change the password 'P#gtitO@D:=~5C.7?IDyF1?dZ2Yo|* above to the one defined when creating the user)
Run all available data migrations:
php yii migrateThe database must be manually created by the user (two steps earlier) for the migrations to work.
You need to have a properly configured MX server (mail exchange server) to:
- register a new user (→ send an email address verification message),
- reset a forgotten password (→ send a password reset token).
Please open the file common/config/main-local.php and provide the correct MX server configuration, for example:
$mailScheme = 'smtp';
$mailHost = 'poczta.o2.pl';
$mailUsername = 'username@o2.pl';
$mailPassword = 'strong123P@SSWORD!';
$mailPort = '587';Then go to frontend/config/params-local.php and set the correct value for the supportEmail parameter:
'supportEmail' => 'username@o2.pl'Most mail servers require that you use exactly the same values (i.e. the same e-mail address) in all these places:
- for
$mailUsernameincommon/config/main-local.php - for
senderEmailincommon/config/params-local.php - for
supportEmailinfrontend/config/params-local.php
I.e. you can only send emails using your account email address.
Here is a couple of links, in case you would have troubles configuring MX:
- using regular email accounts (Using Built-in Transports):
- using specialized email service (Using a 3rd Party Transport):
A technical email sent from this application may be considered as SPAM and blocked by your MX server. Or not delivered by
any other reason. In this case, check the application logs for possible errors. If you're sending emails from a development
environment, you can see each mail prepared for send, as it has a local copy stored in file, in frontend/runtime/debug/mail
folder.
Go to common/config/params-local.php and adjust the application configuration to your needs:
'senderEmail' => 'username@o2.pl',
'senderName' => 'MagiEdit',
'user.passwordResetTokenExpire' => 3600,
'user.passwordMinLength' => 8Several files (namely frontend/config/main-local.php for all environments plus common/config/codeception-local.php and
frontend/config/test.php on development and test environments) includes some predefined keys for cookieValidationKey
property of the request component. These were generated using randomkeygen.com service. If
you are extra sensitive over security, you may consider generating a completely new keys for each of your environments.
Your app should be ready to use. Launch your browser and go to:
http://localhost/niner-games/magiedit.web/frontend/web/
For more detailed testing instructions and technical documentation, visit the project wiki.
This application comes with no users. In order to manage it, you must have at least one user in type of administrator. For security reasons this is done manually. Please note, that you must have direct access to your database (through phpMyAdmin or any other database management tool) to complete this step.
- First, register a regular user account:
http://localhost/niner-games/magiedit.web/frontend/web/account/signup
-
Receive account verification email and verify this account.
-
Login to phpMyAdmin and go to
usertable in themagieditdatabase (adjust these to match your setup):
http://localhost/phpmyadmin/index.php?route=/sql&pos=0&db=magiedit&table=user
- Edit record that corresponds to your selected user and change the value of
typecolumn from1to9.
You are done. Now, you can log in with this user to the application, have access to user management section and change any other user to admin. Please note, that you must have at least one administrator in the system. You cannot delete last administrator, and you cannot delete currently logged-in user.
Tests are located in tests directory. They are developed with Codeception PHP Testing Framework.
By default, there are 3 test suites:
unitfunctionalacceptance
Tests can be executed by running
vendor/bin/codecept run
The command above will execute unit and functional tests. Unit tests are testing the system components, while functional tests are for testing user interaction. Acceptance tests are disabled by default as they require additional setup since they perform testing in real browser.
To execute acceptance tests do the following:
-
Rename
tests/acceptance.suite.yml.exampletotests/acceptance.suite.ymlto enable suite configuration -
Replace
codeception/basepackage incomposer.jsonwithcodeception/codeceptionto install full-featured version of Codeception -
Update dependencies with Composer
composer update -
Download Selenium Server and launch it:
java -jar ~/selenium-server-standalone-x.xx.x.jarIn case of using Selenium Server 3.0 with Firefox browser since v48 or Google Chrome since v53 you must download GeckoDriver or ChromeDriver and launch Selenium with it:
# for Firefox java -jar -Dwebdriver.gecko.driver=~/geckodriver ~/selenium-server-standalone-3.xx.x.jar # for Google Chrome java -jar -Dwebdriver.chrome.driver=~/chromedriver ~/selenium-server-standalone-3.xx.x.jarAs an alternative way you can use already configured Docker container with older versions of Selenium and Firefox:
docker run --net=host selenium/standalone-firefox:2.53.0 -
(Optional) Create
yii2basic_testdatabase and update it by applying migrations if you have them.tests/bin/yii migrateThe database configuration can be found at
config/test_db.php. -
Start web server:
tests/bin/yii serve -
Now you can run all available tests
# run all available tests vendor/bin/codecept run # run acceptance tests vendor/bin/codecept run acceptance # run only unit and functional tests vendor/bin/codecept run unit,functional
By default, code coverage is disabled in codeception.yml configuration file, you should uncomment needed rows to be able
to collect code coverage. You can run your tests and collect coverage with the following command:
#collect coverage for all tests
vendor/bin/codecept run --coverage --coverage-html --coverage-xml
#collect coverage only for unit tests
vendor/bin/codecept run unit --coverage --coverage-html --coverage-xml
#collect coverage for unit and functional tests
vendor/bin/codecept run functional,unit --coverage --coverage-html --coverage-xml
You can see code coverage output under the tests/_output directory.
To test the API, it's recommended to use the Insomnia Portable application.
You can import the file insomnia.json (available in the console/migrations folder of the project) into your copy of Insomnia Portable (note: this may not work with the standalone Insomnia version). This will prepare all the environments (DEV, TEST, UAT, PROD) and API endpoints for testing.