Initial commit

CodeStandards.wiki

@@ -0,0 +1,266 @@
+= Code Standards =
+<<toc>>
+
+This page covers some of the basics of the Flourish code standards.
+
+''This page is a work-in-progress and thus very incomplete.''
+
+== Files ==
+
+=== PHP Tags ===
+
+All PHP files should start with a long PHP tag `<?php`, and '''omit''' the
+closing PHP tag `?>`.
+
+{{{
+#!php
+<?php
+class Example
+{
+	private $member = NULL;
+}
+}}}
+
+Closing PHP tags are omitted because they are unnecessary and if they have any
+white-space after them, can prevent the modification of headers since output
+has already begun. In addition, files should never leave PHP and go to raw
+output, so the closing PHP tag should never be present. If output is required,
+the `echo` statement should be used instead.
+
+'''This is incorrect:'''
+
+{{{
+#!php
+<?php
+class Example
+{
+	private $member = NULL;
+}
+?>
+}}}
+
+Short tags `<?` and `<?=` should not be used since some installations of PHP do
+not support them and Flourish is aimed at high compatibility.
+
+'''This is incorrect:'''
+
+{{{
+#!php
+<?
+class Example
+{
+	private $member = NULL;
+}
+}}}
+
+=== Line Length ===
+
+In general lines should try not to exceed 80 characters in length, however this
+does happen a fair amount. Use best judgment about how the code will be most
+readable.
+
+=== Line Termination ===
+
+All files should be saved in Unix format, meaning that each line should end
+with a single line feed (also known as an LF or `\n`).
+
+== Formatting ==
+
+=== Indenting ===
+
+All code should be indented from the left margin by tab characters and a tab
+width should be set to 4 spaces. All indenting done in the middle of a line
+should be with spaces.
+
+''Please note that these code samples have all tabs replaced by 4 spaces
+because browsers default to 8 spaces per tab and the code highlighter
+automatically converts the tabs to spaces for proper spacing.''
+
+{{{
+#!php
+if ($show) {
+	$message = 'Hello';
+}
+}}}
+
+Large blocks of assignments should have the operators lined up.
+
+{{{
+#!php
+$header  = 'Header';
+$body    = 'Body';
+$body   .= ' with content';
+
+$content   = array();
+$content[] = $header;
+$content[] = $body;
+}}}
+
+All blocks of code, such as `if`, `function`, `switch`, `class` should have the
+contents indented one level. `switch` statements should have the `case` block
+contents indented another level:
+
+{{{
+#!php
+function calculate($output, $value)
+{
+	if ($conditional) {
+		$output += $value;
+	}
+	switch ($value) {
+		case 1:
+			$output *= 1.5;
+			break;
+	}
+}
+}}}
+
+Long arrays without explicit keys and most arrays with explicit keys should
+have one entry per line, indented one level from the line containing the
+beginning of the array. When array contents are indented, all double arrows
+(`=>`) should be lined up with spaces.
+
+{{{
+#!php
+// This is OK
+$types    = array('gif', 'jpeg', 'png');
+
+// This is hard to read and long
+$mappings = array('gif' => 'Graphics Interchange Format', 'jpeg' =>
+'Joint Photographic Experts Group', 'png' => 'Portable Network Graphics');
+
+// This is much easier to read
+$mappings = array(
+	'gif'  => 'Graphics Interchange Format',
+	'jpeg' => 'Joint Photographic Experts Group',
+	'png'  => 'Portable Network Graphics' 
+);
+}}}
+
+=== Blocks ===
+
+All classes and methods should have the opening and closing braces on their
+own line.
+
+{{{
+#!php
+class Example
+{
+	public function getMember()
+	{
+		return $this->member;
+	}
+}
+}}}
+
+The opening brace should '''not''' be on the same line as the class or method
+name.
+
+'''This is incorrect:'''
+
+{{{
+#!php
+class Example {
+	public function getMember() {
+		return $this->member;
+	}
+}
+}}}
+
+All flow-control code blocks, including `if`, `while`, `for`, `foreach`,
+`switch`, etc. should have the opening brace on the same line as the beginning
+of the statement.
+
+{{{
+#!php
+if ($conditional) {
+	$total = 1;
+} else {
+	$total = 2;
+}
+
+while ($conditional) {
+	$total++;
+	$conditional = $total % 5;
+}
+}}}
+
+'''This is incorrect:'''
+
+{{{
+#!php
+if ($conditional)
+{
+	$total = 1;
+}
+}}}
+
+All flow-control code block should also have a single space after the statement
+name before the `(` or `{`. `else` statements should have a space before and
+after the word. `else/if` statements should be written as `elseif`, '''not'''
+`else if`.
+
+{{{
+#!php
+if ($conditional) {
+	$total = 1;
+} elseif($other_condition) {
+	$total = 0;
+} else {
+	$total = 2;
+}
+}}}
+
+== Naming Conventions ==
+
+=== Classes, Methods, Members and Constants ===
+
+All classes are written in `UpperCamelCase`, methods are writen in
+`lowerCamelCase`, members are written in `lower_underscore_notation` and
+constants are written in `UPPER_UNDERSCORE_NOTATION`.
+
+{{{
+#!php
+<?php
+class MyExample
+{
+	const MY_CONSTANT = 'constant';
+
+	private $my_member = NULL;
+
+	public function getMyMember()
+	{
+		return $this->my_member;
+	}
+}
+}}}
+
+=== Variables ===
+
+All variables are written in lower_underscore_notation.
+
+{{{
+#!php
+<?php
+$my_var = 'Hello World';
+}}}
+
+=== Acronyms ===
+
+Acronyms in class, method and constant names are written as all uppercase.
+Acronyms in members and variables are written as all lowercase.
+
+{{{
+#!php
+class USPSRates
+{
+	const APO_FPO_REGEX = '#^\s*(APO|FPO)\s+([A-Z]{2})\s+#i';
+
+	private $web_service_url;	
+
+	public function setWebServiceURL($url)
+	{
+		$this->web_service_url = $url;
+	}		
+}
+}}}

CompilingPHPOnWindows.wiki

@@ -0,0 +1,47 @@
+= Compiling PHP On Windows =
+<<toc>>
+
+''The following instructions were last updated in June 2011, and may be out of
+date.''
+
+The following instructions are meant to help provide a guide for getting
+started with compiling PHP, or PHP extensions, on Windows. If you are looking
+for a non-standard PHP extension, Pierre Joye maintains builds of many at
+http://www.php.net/~pierre/. The official Windows builds are available at
+http://windows.php.net/download/ and include many of the most common
+extensions.
+
+Many extensions will mention vc6, vc9, x86, x64, nts or ts in their filenames.
+The official builds of PHP 5.3 are compiled using Microsoft Visual C++ 2008
+(v9.0), also known as VC9. PHP 5.2 is compiled using Microsoft Visual C++ 6.0,
+also known as VC6. Currently there is no official 64-bit (x64) version of PHP
+for Windows, so all official build are 32-bit, also referred to as x86. Windows
+PHP builds are either thread-safe (TS), or non-thread-safe (NTS). Extensions
+need to be compiled with the same compiler (VC6 or VC9) for the same
+architecture (x86 or x64) and with the same threading configuration (ts or nts)
+as the main PHP install.
+
+== PHP 5.3 ==
+
+To build PHP 5.3 and compile extensions that will be compatible with the
+official releases, you will need the following software installed. Please be
+sure to install the Windows SDK '''BEFORE''' Visual Studio or else you will run
+into issues with libraries being overwritten by older versions.
+
+Please be sure to use the exact versions listen here for compatibility.
+
+ - [http://www.microsoft.com/downloads/en/details.aspx?familyid=e6e1c3df-a74f-4207-8586-711ebe331cdc&displaylang=en Windows SDK v6.1]
+ - [http://download.microsoft.com/download/A/5/4/A54BADB6-9C3F-478D-8657-93B3FC9FE62D/vcsetup.exe Microsoft Visual C++ 2008 Express Edition] (free)
+ - [http://windows.php.net/download/ PHP Source Code]
+ - [http://windows.php.net/downloads/php-sdk/ PHP Compilation Dependencies and SDK Build Tools]
+
+== PHP 5.2 ==
+
+To build PHP 5.2 and compile extensions that will be compatible with the official releases, you will need the following to be installed. Unfortunately there is no free version of Visual C++ 6.0 and the Windows SDK is no longer officially distributed.
+
+ - [http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm Windows Platform SDK February 2003 Edition]
+ - Microsoft Visual C++ 6.0 (commercial only)
+ - [http://www.microsoft.com/downloads/en/details.aspx?familyid=a8494edb-2e89-4676-a16a-5c5477cb9713&displaylang=en Microsoft Visual C++ 6.0 SP2] (free update)
+ - [http://windows.php.net/download/ PHP Source Code]
+ - [http://deioncube.in/files/Extensions/Tools/LibsVc6/ PHP Compilation Dependencies]
+ - ''More to come...''

ConstructorFunctions.wiki

@@ -0,0 +1,10 @@
+= Constructor Functions = 
+
+Constructor functions are functions with the same name as Flourish instance
+classes that accept the same parameters, and return a new object. Their only
+purpose is to work around the fact that up until PHP 5.4, it was not possible
+to chain method calls off of a constructor.
+
+While the constructor functions used to be a manual add-on to Flourish, they
+are now defined inside of fLoader and will be available when using fLoader
+to load Flourish.

ContributorLicenseAgreements.wiki

@@ -0,0 +1,20 @@
+= Contributor License Agreements =
+
+In order for anyone other than myself to contribute ideas, code or
+documentation to Flourish, I ask that they sign a contributor license
+agreement (CLA). This document is used to define the terms under which
+contributions to Flourish are made. They also could potentially be used in the
+case of a law suit to help in defense.
+
+Individuals contributing any code, documentation or ideas that they own the
+rights to should sign the [/files/flourish_cla.pdf
+Flourish Contributor License Agreement]. If you are submitting intellectual
+property (IP) owned by your employer, they will need to sign the
+[/files/flourish_ccla.pdf Flourish Corporate Contributor
+License Agreement]. Please be aware that an individual who is covered under a
+corporate CLA will also need to submit an individual CLA if they submit any IP
+that is not owned by their employer.
+
+ - '''[/files/flourish_cla.pdf Flourish Contributor License Agreement]'''
+ - '''[/files/flourish_ccla.pdf Flourish Corporate Contributor License Agreement]'''
+