<commit_before>README.md

<NAME>

2014-12-8 VCard-Tools PHP toolbox

MIT License http://opensource.org/licenses/MIT

Composer Package: evought/vcard-tools

#What This Project Is#

This effort is a set of tools for manipulating VCards (RFC 6350) in PHP,
including in-memory representation, database persistence, and HTML templating.
The tools build on two other works, the VCard PHP class by <NAME>,
<NAME> (https://github.com/nuovo/vCard-parser) and a sample VCard SQL
schema by George_h on Stackoverflow for RFC6868/VCard 3.0.
VCard-Tools marries an improved VCard class with a set of classes for database
persistence (based on George_h's schema) and flexible HTML output targeting
VCard 4.0 (RFC 6350) compliance, defined in the EVought\vCardTools namespace.
It also includes a growing suite of PHPUnit tests.

This file describes the project, setup, and basic usage.
Also see the [Wiki](https://github.com/evought/VCard-Tools/wiki) for additional
information, including class hierarchy and design discussion.

The package is currently a pre-release and should not be considered production
code.
The GitHub repository lays out milestones and schedule toward a 1.0 release and
the anticipated features.

#License#

All components are under the [MIT License](license.txt).

#Components#

The project consists of php classes in the EVought\vCardTools namespace.
The primary classes of interest are vCard, VCardDB, and Template.
The sql schema (MySQL) is defined in sql/, documentation materials in doc/, and
PHPUnit test cases under tests/.
Pre-defined templates are in src/templates/.
Setting up the database is described below.
There is a [Phing](http://www.phing.info/) script for automating project
maintenance tasks. I also set things up to be usable from NetBeans IDE.

Internal dependencies are partitioned out.
VCard may be used without the Template or VCardDB classes.
The templating code can be used along with the original VCard class *with or
without the database persistence*, and the database persistance does not require
the use of the Template class.

The HTML templating is designed with CSS styling in mind.
Classes and roles are clearly indicated in the markup as styling hooks and it
is simple to present different output for, say, Individual versus Organization
or summary versus full information.
In a live website, I intend that it should be easy for the user to go from a
search-list to individual detailed listings, export the raw .vcf text or even,
potentially, generate a QR code.
I expect to add a template for proper hcard output, but it should not be
difficult (at all) for someone to use the mechanism to produce a conformant
hcard using the existing code.

The Database code is intended to be adaptable to somewhat different database
setups, and this will continue as a future design direction.
SQL queries used to fetch/store/search VCards are defined in an external .ini
file to both ease maintenance and enable customization.

##Autoloading##

The source files and classes are laid out to be PSR-4 compliant and should
therefore work with compliant autoloaders.
Composer generates such an autoloader automatically, which may be included
from vendor/autoload.php.

##Requirements##

The project was developed against
* PHP 5.5 (5.5.20)
* MySQL 5.5 (5.5.38)

The library is known to _not_ work with PHP 5.4, but the Continuous Integration
server does regularly test against [hhvm](http://hhvm.com/) (Hip Hop Virtual
Machine).

Dependencies are tracked through [Composer](https://getcomposer.org/).
The Composer tool, with its configuration in composer.json obtains, tracks, and
installs the components needed to build and use VCardTools.
Composer also provides the autoloading script required to use the vCardTools
classes in an application.

_NOTE_: Due to issue [#94](https://github.com/evought/VCard-Tools/issues/94) the
latest Composer snapshot is required.
The underlying defect in Composer has been fixed but has not yet been packaged
in a regular release.

Composer will locate and install two other php libraries required by VCardTools,

* [rhumsaa/uuid](https://github.com/ramsey/uuid): A tool for generating
RFC 4122 version 1, 3, 4, and 5 universally unique identifiers (UUID).

* [evought/data-uri](https://gist.github.com/evought/b817103313f5ddff5817): 
A convenient class for working with Data URIs in PHP. This class is loaded from
a Gist and currently requires a custom repostory definition
([Issue #103](https://github.com/evought/VCard-Tools/issues/103), see below.)

To develop and run tests, composer will also install:

* Phing
* PHPUnit
* PHPDocumentor

and their dependencies.

I am doing most of my development on a Intel-based Fedora Linux 20 workstation
and the Continuous Integration server regularly tests the code in a clean
Ubuntu Linux environment.

# Including Via Composer #

To include this library in a larger project via Composer, you first must have
a [composer.json](https://getcomposer.org/doc/00-intro.md) for your project.
That file must include the following extra settings:

    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/evought/DataURI.git"
        }
    ],
    "require": {
            "evought/data-uri": "*@dev",
            "evought/vcard-tools": "dev-master"
        }

The repositories section is required to fetch the data-uri package directly from
github because it is not yet available through packagist, Composer's default
repository ([Issue #103](https://github.com/evought/VCard-Tools/issues/103)).
For security reasons, Composer will not automatically load a package from a
non-standard repository unless you tell it explicitly to do so.
For the same reason, your require section has to include both evought/data-uri
and evought/vcard-tools along with any other dependencies your package may
require.

If you are only using the non-database portions of VCard-Tools, this should
be sufficient to get you going and a "composer install" should fetch and install
this package. If you are also using the database portions, things are a bit
more complicated because you will have to install the database schema into
your database as well and be able to update the schema as you upgrade to
new versions of VCard-Tools. VCard-Tools provides utilities to make that
process easier and allows you to customize the process if your situation is
unusual. You will want to read the Database Setup section thoroughly.
If you check out the sources for this package in a separate
directory, set it up, and run its tests to see how it works stand-alone, that<commit_msg>Last commit to fix #103. Removed instructions for data-uri repository workaround.<commit_after>README.md

<NAME>

2014-12-8 VCard-Tools PHP toolbox

MIT License http://opensource.org/licenses/MIT

Composer Package: evought/vcard-tools

#What This Project Is#

This effort is a set of tools for manipulating VCards (RFC 6350) in PHP,
including in-memory representation, database persistence, and HTML templating.
The tools build on two other works, the VCard PHP class by <NAME>,
<NAME> (https://github.com/nuovo/vCard-parser) and a sample VCard SQL
schema by George_h on Stackoverflow for RFC6868/VCard 3.0.
VCard-Tools marries an improved VCard class with a set of classes for database
persistence (based on George_h's schema) and flexible HTML output targeting
VCard 4.0 (RFC 6350) compliance, defined in the EVought\vCardTools namespace.
It also includes a growing suite of PHPUnit tests.

This file describes the project, setup, and basic usage.
Also see the [Wiki](https://github.com/evought/VCard-Tools/wiki) for additional
information, including class hierarchy and design discussion.

The package is currently a pre-release and should not be considered production
code.
The GitHub repository lays out milestones and schedule toward a 1.0 release and
the anticipated features.

#License#

All components are under the [MIT License](license.txt).

#Components#

The project consists of php classes in the EVought\vCardTools namespace.
The primary classes of interest are vCard, VCardDB, and Template.
The sql schema (MySQL) is defined in sql/, documentation materials in doc/, and
PHPUnit test cases under tests/.
Pre-defined templates are in src/templates/.
Setting up the database is described below.
There is a [Phing](http://www.phing.info/) script for automating project
maintenance tasks. I also set things up to be usable from NetBeans IDE.

Internal dependencies are partitioned out.
VCard may be used without the Template or VCardDB classes.
The templating code can be used along with the original VCard class *with or
without the database persistence*, and the database persistance does not require
the use of the Template class.

The HTML templating is designed with CSS styling in mind.
Classes and roles are clearly indicated in the markup as styling hooks and it
is simple to present different output for, say, Individual versus Organization
or summary versus full information.
In a live website, I intend that it should be easy for the user to go from a
search-list to individual detailed listings, export the raw .vcf text or even,
potentially, generate a QR code.
I expect to add a template for proper hcard output, but it should not be
difficult (at all) for someone to use the mechanism to produce a conformant
hcard using the existing code.

The Database code is intended to be adaptable to somewhat different database
setups, and this will continue as a future design direction.
SQL queries used to fetch/store/search VCards are defined in an external .ini
file to both ease maintenance and enable customization.

##Autoloading##

The source files and classes are laid out to be PSR-4 compliant and should
therefore work with compliant autoloaders.
Composer generates such an autoloader automatically, which may be included
from vendor/autoload.php.

##Requirements##

The project was developed against
* PHP 5.5 (5.5.20)
* MySQL 5.5 (5.5.38)

The library is known to _not_ work with PHP 5.4, but the Continuous Integration
server does regularly test against [hhvm](http://hhvm.com/) (Hip Hop Virtual
Machine).

Dependencies are tracked through [Composer](https://getcomposer.org/).
The Composer tool, with its configuration in composer.json obtains, tracks, and
installs the components needed to build and use VCardTools.
Composer also provides the autoloading script required to use the vCardTools
classes in an application.

_NOTE_: Due to issue [#94](https://github.com/evought/VCard-Tools/issues/94) the
latest Composer snapshot is required.
The underlying defect in Composer has been fixed but has not yet been packaged
in a regular release.

Composer will locate and install two other php libraries required by VCardTools,

* [rhumsaa/uuid](https://github.com/ramsey/uuid): A tool for generating
RFC 4122 version 1, 3, 4, and 5 universally unique identifiers (UUID).

* [evought/data-uri](https://github.com/evought/DataURI): 
A convenient class for working with Data URIs in PHP.

To develop and run tests, composer will also install:

* Phing
* PHPUnit
* PHPDocumentor

and their dependencies.

I am doing most of my development on a Intel-based Fedora Linux 20 workstation
and the Continuous Integration server regularly tests the code in a clean
Ubuntu Linux environment.

# Including Via Composer #

To include this library in a larger project via Composer, you first must have
a [composer.json](https://getcomposer.org/doc/00-intro.md) for your project.
That file must include the following extra setting:

    "require": {
            "evought/vcard-tools": "dev-master"
        }

If you are only using the non-database portions of VCard-Tools, this should
be sufficient to get you going and a "composer install" should fetch and install
this package. If you are also using the database portions, things are a bit
more complicated because you will have to install the database schema into
your database as well and be able to update the schema as you upgrade to
new versions of VCard-Tools. VCard-Tools provides utilities to make that
process easier and allows you to customize the process if your situation is
unusual. You will want to read the Database Setup section thoroughly.
If you check out the sources for this package in a separate
directory, set it up, and run its tests to see how it works stand-alone, that
{'fraction_non_alphanumeric': 0.056832901554404146, 'fraction_numerical': 0.011415155440414508, 'mean_word_length': 4.422739244951712, 'pattern_counts': {'":': 8, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 17, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5638058', 'n_tokens_mistral': 3347, 'n_tokens_neox': 3169, 'n_words': 1739}