README

Short URL Libs
==============
v.0.9.8

libs for creating short urls

author:
	pkhalil

Overview
--------

base class and interface for extended modules support


Features
--------

abstract, cacheing, easy to use


Conventions
-----------
use PEAR or Zend naming conventions ... 

http://pear.php.net/manual/en/standards.php
http://framework.zend.com/manual/en/coding-standard.html
see also 
http://www.horde.org/horde/docs/?f=CODING_STANDARDS.html
http://codex.wordpress.org/WordPress_Coding_Standards

examples
http://phpkitchen.com/2005/03/advantages-of-using-the-pear-class-naming-convention/

see also php code sniffer
 $ phpcs -i

### notes 

use $_foo or _foo() for private vars n functions

don't use __foo() in user functions , thats reserved for magic ..

translate with _("hello world") using gettext and .po files

html5 naming conventions class="header", "section", "article", "aside" etc.

chromeless web apps for iphone
<meta name="apple-mobile-web-app-capable" content="yes" />

remove png color profiles
pngcrush -rem gAMA -rem cHRM -rem iCCP -rem sRGB infile.png outfile.png

BAD: echo 'Hello, my name is' . $firstName . $lastName . ' and I live in ' . $city;

GOOD: echo 'Hello, my name is' , $firstName , $lastName , ' and I live in ' , $city;

### KEYWORDS:

#### Specs:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt "RFC Keywords")

#### Changelog updates:

ADDED:
FIXED:
CHANGED:
UPDATED:
REMOVED:



Build
-----

Build using ant

this will generate docs, unit test code, acceptance (functional) test the pages,
generate coverage reports, code sniff for coding standard violation, check for
pmd(programming mistake detection), etc ...

just run ant in base folder with build.xml

for a list of options check out

	ant -p 

enjoy :)

Deploy:
-------

using capistrano

this will check out the code on multiple machines, setup symlinks, allow for
rollbacks, set up databases, set up vhosts, restart the server, etc ... 

	 project
	      |______config   (this is for storing the capistrano deploy.rb file)
	      |______log      (for server logs)
	      |______private
	      |______public   (the webserver vhost root with all the PHP files)

	$ mkdir -p project/config
	$ mkdir -p project/log
	$ mkdir -p project/private

or just use capistrano to do this 

	$ cap deploy:setup
	$ cap deploy
	$ cap rollback # if there are errors

#### more notes

setup new server
	$ cap HOSTS=net.pjkix.com deploy:setup
	
upload files instead of full deploy

	$ cap deploy:upload FILES=templates,controller.rb
 
Dir globs are also supported:
 
	$ cap deploy:upload FILES='config/apache/*.conf'

rollback if error 
	$ cap rollback



#### about capistrano

dir structure

	myapp/releases
	myapp/current -> myapp/releases/xxxxx
	myapp/shared

	$ cap deploy

		deploy:update_code
		deploy:symlink
		deploy:restart

Displays the `diff' since your last deploy

	$ cap deploy:pending
	

Maintenance page ...

	 $ cap deploy:web:disable \
	REASON="hardware upgrade" \
	UNTIL="12pm Central Time"
	
and then ...

	$ cap deploy:web:enable
	
##### shared stuff ... 

myapp/shared/config/database.yaml
myapp/shared/images/
myapp/shared/data/


UML:
----
3.2. UML Based Processes for OOA&D 

It is important to understand that UML is a notation for OOA&D. It does not
prescribe any particular process. Whatever process is adopted, it must take the
system being constructed through a number of phases.

1. Requirements Capture. This is where we identify the requirements for the
system, using the lan- guage of the problem domain. In other words we describe
the problem in the “customer's” terms.

2. Analysis. We take the requirements and start to recast them in the language
of a putative solu- tion—the solution domain. At this stage, although thinking
in terms of a solution, we ensure we keep things at a high level, away from
concrete details of a specific solution—what is known as ab-straction.

3. Design. We take the specification from the Analysis phase and construct the
solution in full detail. We are moving from abstraction of the problem to its
realization in concrete terms.

4. Build Phase. We take the actual design and write it in a real programming
language. This includes not just the programming, but the testing that the
program meets the requirements (verification), testing that the program actually
solves the customer's problem (validation) and writing all user documentation.

http://yuml.me/diagram/usecase/[Local]-(ant), [Local]-(cap), [Local]>(svn) , (svn)<(ci) , (ant)>(svn), (cap)>(dev), (dev)>(www).

http://yuml.me/diagram/usecase/%5BLocal%5D-%28ant%29%2C%20%5BLocal%5D-%28cap%29%2C%20%5BLocal%5D%3E%28svn%29%20%2C%20%28svn%29%3C%28ci%29%20%2C%20%28ant%29%3E%28svn%29%2C%20%28cap%29%3E%28dev%29%2C%20%28dev%29%3E%28www%29

[User]-(svn)
(svn)>(lint)
[ci]-(svn)
[ci]-(build)
(build)>(test)
[User]-(cap deploy)
(cap deploy)>(www)

http://yuml.me/diagram/usecase/[User]-(svn), (svn)>(lint), [ci]-(svn), [ci]-(build), (build)>(test), [User]-(cap deploy), (cap deploy)>(www).

http://yuml.me/diagram/usecase/%5BUser%5D-%28svn%29%2C%20%28svn%29%3E%28lint%29%2C%20%5Bci%5D-%28svn%29%2C%20%5Bci%5D-%28build%29%2C%20%28build%29%3E%28test%29%2C%20%5BUser%5D-%28cap%20deploy%29%2C%20%28cap%20deploy%29%3E%28www%29

use case ... 

scenerio ... 

 Use-case diagram
	

Class diagram
	

Sequence diagram
	

Collaboration diagram
	

State diagram
	

Activity diagram
	

Deployment diagram 


Todo:
-----
* export git -> svn 

* automate build / testing / end to end / continuous integration / automated deploys
ant + phpunit + selenium (rc) + cruisecontrol + phpundercontrol + capistrano = :)

* document using uml / phpdoc / markdown

* config using yaml

* setup ant task for compressing js/css with yuicompressor

* setup svn to use php lint & js lint

* setup phpcs to use own coding standard + jslint




---



URL Shorteners Background
=========================

* tinyurl.com -  the baseline standard
* bit.ly - http://bit.ly/apidocs - stats n tracking
* is.gd - 
* tr.im - 
* cli.gs - http://blog.cli.gs/api
* tweetburner - 
* many more ... 

interersting articles
---------------------

* http://dooleyonline.typepad.com/dooley_post/2009/02/comparison-of-url-shorteners.html
* http://www.toprankblog.com/2009/01/11-best-url-shortening-services-vote-your-favorite/
* http://searchengineland.com/analysis-which-url-shortening-service-should-you-use-17204

Issues
------
* short + friendly
* stats
* api
* seo - 301 no framing


Recommendations
---------------
personally i would recommend bit.ly or tinyurl.com as these are the most widely used services.


Notes
-----

these are notes about the short-url module itself, there are a few supporting files as well.

Documentation
-------------
see inline or generated phpdocs for more detail.

url shortening services have been updated. it should now be easy to use a
variety of url shorteners from a single backend library as well as a front end
solution. currently the backend library defaults to using bit.ly. the library
also has built in cacheing using memcache and mysql db. this new code is also
backed up by a unit test suite for the entire library.

currently this has been plugged into the show page already and is up on dev. i'm
currently working with joe and will to get this plugged into the flash player.
unfortunetly this requires some work from will to get it properly engineered and
intergrated since the player was building up its own message and urls.

there are a few issues with bit.ly themselves, for isntance i don't see anyway
in their interface to track urls that are shortened with their api service and
not the web interface. some of these do show up however in a recently clicked
list. if we do need to have aggregate stats for these it should be possible to
build up an admin dashboard using the short urls stored in the database.

### usage

<code>
	require_once 'ShortUrl.php';
	$myShortUrl =  ShortUrlFactory::getUrlService(); // use default service
	$myShortUrl =  ShortUrlFactory::getUrlService(ShortUrlFactory::TINY_URL); // or a specific one
	echo $myShortUrl->getShortUrl($url);
</code>

### Implementation

we're currently going with bit.ly as our default url shortener.

using the following credentials which are located in the bit.ly class itself.
(this could be made a config var later but the configs are already a mess of
used and unused vars)

	private $api_key = '<API_KEY>';
	private $user = '<USER>';
	

the urls are not pre-generated and need to be made upon request. 
this will require a link to a redirect which checks a token and handles the shortening

the player also needs to make a call the the backend to request a message and a shortened url

### Module Overview

	lib/
		|-- ShortUrl.php 		(base lib and factory method)
		|-- ShortUrl.ut.php 	(phpunit tests)
		|-- ShortUrl.sql 		(db schema setup)
		|-- ShortUrl/ 		(extensions for specific shortening services)
			|-- Bitly.php
			|-- Cligs.php
			|-- Isgd.php
			|-- Tinyurl.php
			`-- Trim.php

---


Project Structure
---------

short-urls

	.
	|-- CHANGELOG
	|-- Capfile
	|-- INSTALL
	|-- README
	|-- build
	|   \-- <GENERATED>
	|-- build.number
	|-- build.properties
	|-- build.xml
	|-- config
	|   |-- PHP
	|   |   `-- CodeSniffer
	|   |       `-- Standards
	|   |           `-- Kix
	|   |               |-- KixCodingStandard.php
	|   |               `-- Sniffs
	|   |                   `-- Commenting
	|   |                       `-- DisallowHashCommentsSniff.php
	|   |-- PHPDocConfig.ini
	|   |-- cc-phpuc-build.xml
	|   |-- cc-phpuc-config.xml
	|   |-- cc-phpuc-setup.sh
	|   |-- config.yaml
	|   |-- database.yml
	|   |-- deploy.rb
	|   |-- index.php
	|   |-- phpcs-CodingStandard.php
	|   |-- pmd-ruleset.xml
	|   |-- sample-deploy.rb
	|   |-- simple-deploy.rb
	|   |-- templates
	|   |   |-- wp-config.php.erb
	|   |   `-- wp-vhost.conf.erb
	|   `-- wp-deploy.rb
	|-- data
	|   `-- db.sqlite
	|-- example
	|   |-- demo.phtml
	|   |-- scripts
	|   |   |-- bitlyAPI.js
	|   |   `-- shortUrl.js
	|   `-- styles
	|       `-- default
	|           `-- main.css
	|-- lib
	|   |-- MyDb.ini
	|   |-- MyDb.php
	|   |-- ShortUrl
	|   |   |-- Bitly.php
	|   |   |-- Cligs.php
	|   |   |-- Isgd.php
	|   |   |-- Tinyurl.php
	|   |   `-- Trim.php
	|   |-- ShortUrl.php
	|   |-- ShortUrl.sql
	|   |-- debug.class.php
	|   |-- memcache.class.php
	|   |-- memcache.ut.php
	|   `-- twitter.class.php
	`-- tests
	    |-- AcceptanceTestSuite.html
	    |-- AcceptanceTests
	    |   |-- AllTests.php
	    |   |-- DemoTest.ft.php
	    |   `-- demo.ft.html
	    |-- AllTests.php
	    |-- README
	    |-- ShortUrl
	    |   `-- ShortUrl_TinyurlTest.php
	    |-- ShortUrlTest.php
	    |-- ShortUrlTestSuite.php
	    |-- phpunit-bootstrap.php
	    `-- phpunit.xml