Installation and Setup

• Introduction
• Installing Wave Framework
• Server Requirements
• Successful Output from Compatibility Script

Introduction

This document gives a complete overview about the installation procedure of Wave Framework to a web server.

Installing Wave Framework

• 1 - Unpack the downloaded archive of Wave Framework or go to the repository folder if you downloaded through Git or Mercurial.
• 2 - Configuration file '/config.ini' in root directory of the archive should be configured according to your needs. Configuration file has multiple comments about each setting, but they can be left undefined and unchanged at first, since the Framework is able to define defaults for most settings by itself.
• 3 - Upload the entire archive to your server and make Filesystem folder '/filesystem/' and all of its subfolders writable by PHP with command 'chmod 0755' or giving rights using an FTP program like FileZilla (Right click on folder -> File Permissions -> Numeric value -> 0755). This is not required on Windows server (or Windows localhost) since Windows has folders writable by default.
  • On some servers the FTP account is configured so that 0755 will not allow PHP to actually write to these folders if you set the rights over FTP, so you should either ask the administrator to change the account permissions or set the folder permissions to 0777 and see if that works when 0755 did not (this is less secure however, so you should only do it temporarily).
  • Some servers modify the files uploaded through FTP in some way, often breaking line breaks and thus functionality of the scripts. If you encounter problems and there is no clear error message, then make sure that the uploaded files are correctly stored on the server. Upload should work correctly if you upload files in Binary mode (In FileZilla it is 'Transfer -> Transfer Type -> Binary').
• 4 - Wave Framework requires servers ability to redirect all requests to '/index.php' file, thus Apache RewriteEngine or Nginx HttpRewriteModule has to be used. Look at points 5A or 5B, depending on your server.
• 5A - Apache
  • On most server setups the Apache-related settings in this list should already be enabled and everything should work, but in case you run into problems and you cannot edit Apache configuration yourself, then ask for assistance from your hosting provider.
  • Make sure that you uploaded '/.htaccess' and '/tools/.htaccess' files to the server, as sometimes they may not be uploaded due to operating system thinking they are hidden. If possible, you should actually implement these rewrite directives from those files to your main Apache server configuration and remove the '.htaccess' files, since this can improve the performance, but if this is not possible then keeping the '.htaccess' files in your root folder is perfectly common practice.
  • Apache also needs to support '.htaccess' directives from those files, so make sure that 'AllowOverride' setting is 'All' in Apache directory configuration. This is usually enabled by default on most servers.
  • Since RewriteEngine is required for URL rewrites, your server needs to have the module loaded, which means that the line 'LoadModule rewrite_module modules/mod_rewrite.so' needs to be uncommented in Apache. This is usually enabled by default on most servers.
  • On some hosting environments the line 'Options +FollowSymLinks' in '.htaccess' may throw an error, so if an error is thrown then I suggest commenting or removing that line and trying the compatibility script again.
• 5B - Nginx
  • For rewrites to work properly you need to place the configuration settings found in '/nginx.conf' file to your Nginx server configuration. This is more complicated than setting up redirects locally on Apache servers, since a lot of Nginx servers have very different configurations and just a single configuration file (Nginx has no '.htaccess' like functionality) and you need to implement your configuration inside that main configuration. If you know a little about Nginx server configuration, then it should not be a problem.
• 6 - Test if server is set up properly by making a request to '/tools/compatibility.php' script and fix any errors that Compatibility script might throw. Warnings can be ignored, but Wave Framework works at its best if it encounters no warnings in Compatibility script, so make sure to read the messages next to warnings.
• 7 - Access the root file with a web browser. If 'Hello Wave' is shown together with a pretty logo, without any errors, then everything should be up and running! There is no setup script that needs to be run separately and you can start developing your application right away.
  • If the page shows an error message, then make sure that the '/filesystem/' folders are writable and that the configuration steps above have been followed.
  • Make sure that the files were uploaded correctly and that FTP did not convert line breaks to single line in uploaded files. If it did, then fix this by uploading files in Binary mode.
  • You can also take a look at '/tools/debugger.php' script in case you encounter errors even if Compatibility script says that everything is alright with the server. If Debugger script does not show any warnings and your page still shows errors, then the error happens in core, such as version incompatibility, file permissions and more. Double check that you have followed the previous steps.
  • If the text is shown, but the logo picture is seems to be not found, then the problem might be that you are using a proxy that attempts to load static files by itself and the requested file '/resources/images/160x160&logo.png' does not actually exist. This is because that URL includes on-demand resize parameters that can only be used when file is loaded through Wave Framework itself. You can serve static files through a proxy, but in this case you cannot use the 'dynamic loading of resources' functionality of Wave Framework.
• 8 - Important! Make sure to change 'http-authentication-username' and 'http-authentication-password' settings in '/config.ini' file (line #36 and #37). These are used to authenticate access to developer tools in '/tools/' directory and it may pose a security risk if left unchanged as all downloaded archives have the same username and password at first.

Where to next?

Wave Framework has multiple tutorials you can try out in order to learn how Wave Framework can be used to build various web services and websites. Even if you have not worked with API's and MVC-specific frameworks before, getting a good grip on such a development is not very difficult with Wave. Tutorials are available in the Tutorials section here.

Server Requirements

Wave Framework requires a server that allows to route all requests to Index Gateway file (/index.php). Index Gateway does not work without URL rewriting. It is possible to use Wave Framework's API without Index Gateway, but in this case you need to develop your own gateway that does not require such HTTP request URL rewriting.

Apache

Apache and mod_rewrite (RewriteEngine) is required if you intend to use Index Gateway for website as well as default API Handler. Apache .htaccess file is included in the archive that should do everything server needs to make it work, if the mod_rewrite module is supported by Apache. Because RewriteEngine directives are loaded from local .htaccess files, then Apache also needs to support .htaccess files. If RewriteEngine has problems, then make sure that your Apache setting has 'AllowOverride' set to 'All' instead of 'None' in directory settings. RewriteEngine module is also required, so the 'LoadModule rewrite_module modules/mod_rewrite.so' line has to be included or uncommented from Apache configuration.

Nginx

Wave Framework also supports Nginx server. Nginx does not have .htaccess style local settings for web server, thus these settings have to be written in Nginx configuration itself. Recommended settings for Nginx are stored in /nginx.conf file. You have to manually place them in Nginx server configuration.

PHP

PHP version 5.3.3 or newer is required.

Wave Framework also uses Zlib extension for compressed output, PDO extension for database connections, GD Image Library is used to dynamically resize images, Mcrypt is used for crypted input and output, Fileinfo extension for File Handler and Zip extension for automatic update scripts together with FTP, APC is used to improve the performance of PHP and caching, SimpleXML is used to support XML stream as API input, cURL is used for external requests, . These extensions come with PHP and should be enabled by default, but if they are not enabled then compatibility script will warn you about it and recommend what you should do.

Filesystem

It is also required that /filesystem/ folder and all of its subfolders are writable by PHP. This is not required on Windows server, since folders are already writable.

Successful output from Compatibility Script

SUCCESS: PHP is version 5.3.0 or above
SUCCESS: PHP setting short_open_tag is enabled
SUCCESS: PDO is supported
SUCCESS: PDO MySQL is supported
SUCCESS: PDO SQLite is supported
SUCCESS: PDO PostgreSQL is supported
SUCCESS: PDO Oracle is supported
SUCCESS: PDO MSSQL is supported
SUCCESS: Zlib is supported
SUCCESS: APC PHP is supported
SUCCESS: SimpleXML is supported
SUCCESS: cURL is supported
SUCCESS: Fileinfo is supported
SUCCESS: Mcrypt is supported
SUCCESS: Zip is supported
SUCCESS: FTP is supported
SUCCESS: Memcache is supported
SUCCESS: GD Graphics Library is supported
SUCCESS: Apache server is used
SUCCESS: Apache mod_rewrite extension is supported
SUCCESS: .htaccess file is present
SUCCESS: /filesystem/ is writable
SUCCESS: /filesystem/cache/ is writable
SUCCESS: /filesystem/cache/images/ is writable
SUCCESS: /filesystem/cache/output/ is writable
SUCCESS: /filesystem/cache/resources/ is writable
SUCCESS: /filesystem/cache/custom/ is writable
SUCCESS: /filesystem/cache/tags/ is writable
SUCCESS: /filesystem/messenger/ is writable
SUCCESS: /filesystem/keys/ is writable
SUCCESS: /filesystem/limiter/ is writable
SUCCESS: /filesystem/sessions/ is writable
SUCCESS: /filesystem/logs/ is writable
SUCCESS: /filesystem/errors/ is writable
SUCCESS: /filesystem/tokens/ is writable
SUCCESS: /filesystem/tmp/ is writable
SUCCESS: /filesystem/userdata/ is writable
SUCCESS: /filesystem/backups/ is writable
SUCCESS: /filesystem/static/ is writable
SUCCESS: /filesystem/updates/ is writable
SUCCESS: /filesystem/data/ is writable