Thanks for your interest in helping out! In order to be able to contribute, you will need an environment in which to develop. A detailed setup is provided below.
You're free to contribute in any open issue that's not being tackled by anyone at the moment. However, if there's not an specific issue for the thing you want to make, make sure to open an issue or create a thread in the forums first to verify it's something that the community is interested in! Also, when contributing, please follow the contribution rules:
- Format the code using php-cs-fixer before creating a pull request. The rules are shipped with the code, on the
php-cs.distfile that PHP-CS-Fixer will automatically pick up. - The whole codebase is in english: please use english variable names/comments/commit messages and whatnot.
You need a bunch of things to be installed on the system in order to run the website (a Linux/UNIX machine is recommended, as most tools are not officially designed to run on other OS. Something like Vagrant is an alternative if your OS is not *nix), so let's get on with that:
Note: Installation instructions for the following software are not provided since that would greatly increase the length of this guide. All of it is fairly popular and well-documented, so you should be able to easily find this stuff online. Do note that the versions specified in the list are not necessarily minimal requirements, it's just that the website has simply not been tested with releases prior to those, and it may not work correctly.
- PHP 7.1+
- Plus the phpredis extension. Also available on PECL (
pecl install redis).
- Plus the phpredis extension. Also available on PECL (
- Redis 3+
- MySQL
- Nginx + php-fpm (you can find a sample Nginx config at the end) / Apache
- Composer
- NodeJS (latest stable version)
- ElasticSearch 5.5+ [Instructions]
- ElasticSearch requires a recent JDK 8 version. You may need to use a backport from a newer OS release.
- Go 1.8+
The first thing to do after cloning the project itself is downloading the project dependencies. You can achieve this by running composer install and npm install afterwards. This step may take a while.
While you're downloading, you can copy the .env.example file on the project root to .env, and modify its contents to the ones correct for your MySQL setup (username, pwd, table name, etc). Alternatively, you can set each of the variables as a true environment variable on your system.
After .env file has been set up and the composer dependencies have all been installed, you must run, from the project root:
./vendor/bin/doctrine orm:schema:update --forceto create the database schema required by the websitephp app/console app:bots:synchronizeto create the bot users.
At this point, the website will work, but with no styling at all. For that, you will need to compile the javascript & css. Executing npm run build will take care of it! Now it truly works. Well, except the translation area...
The website uses realtime translation based on websockets. Since PHP is not really ideal for the long-running processes that websocket technology requires, a simple Go server is used instead. To get it, run go get github.com/subtitulamos/subtitulamos-translate (You may need to set GOPATH environment variable if you didn't already). The go get command specific above will both download the source from Github and compile the binary. To quickly get the server started, you can use $GOPATH/bin/subtitulamos-translate -redis-pubsub-env <envname>, where <envname> should equal the value of your ENVIRONMENT env variable. Once this is done, you will be able to fully translate.
Note: You will generally not need to modify the Go server since all the relevant logic is on PHP, and it is just broadcasted via Redis pub-sub system to the Go process, which simply relies it to the connected clients.
Once set up, you will see that any modification to a javascript or CSS file requires you to rebuild said file. To greatly speed up development, you can run npm run watch, which will start a webpack and postcss watcher and automatically compile the JS/CSS the moment you change them.
Aditionally, it may be annoying to run the realtime translation service every time. For that, supervisord is actually a fairly simple and great way to automatically launch/restart the binary. Once again there're better tutorials out in the web than anything that could be written here, specially since the rt translation binary is so simple and doesn't really require much setup besides passing the args (for detail on those, see the docs.
To add new columns to the database, simply edit the model files (or create a new one!) inside app/Entities, adding new private field(s) with the @ORM annotation (see the Doctrine docs for details on the annotations). Once that's done, run ./vendor/bin/doctrine orm:generate-ent ./ to generate getter/setters for the field(s) you just created. Afterwards, you'll probably want to update your database, there's two ways:
- See a diff with your DB schema
./vendor/bin/doctrine orm:sch:update --dump-sql, and run these queries manually (This is the safe option). - Update the DB schema (caution, this can destroy data if you removed a column/table):
./vendor/bin/doctrine orm:sch:update --force.
Here's an Nginx config that should work with the website provided it's running on a server/vagrant box. You need to at least replace the root and and upstream parts with the right paths, and of course any ports you may have changed from the default.
server {
listen 80;
server_name subtitulamos.test;
root /path/to/subtitulamos/files;
location / {
index index.php index.html;
try_files $uri $uri/ /index.php?$query_string;
}
# Pass the php scripts to declared upstream sv
location ~ \.php(/|$) {
# Unmodified fastcgi_params from nginx distribution.
include fastcgi_params;
fastcgi_split_path_info ^(.+\.php)(/.*)$;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;
try_files $uri $uri/ /index.php$is_args$args;
fastcgi_pass php;
}
location /translation-rt {
proxy_pass http://127.0.0.1:8080;
proxy_redirect off;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_set_header X-NginX-Proxy true;
# For websockets
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
# Define fastcgi pass upstream (php-fpm must be configured to listen on a unix socket)
upstream php {
server unix:</path/to/php-fpm/socket/file>;
}