Make 128-bit UUIDs the primary key for all Contacts. Assure that any UUID already assigned gets preserved and that a routine is available to create (and return) a new UUID prior to storage (MySQL has a built-in as one possibility).

VCardDB should be refactored to make better use of prepared statements, particularly when, for instance, fetching a series of VCards or a series of ADR records for one VCard. Specifically:

• Shall rework close multiple fetches/stores inside loops to reuse prepared statements where possible.
• May cache some prepared statements across calls, but if so, must have a simple mechanism to force clearing of all prepared statements.
• Should look toward sharing code for very similar fetches of different VCard properties (e.g. ORG and ADR) where looking up SQL/Prepared Statement and a column map could handle both properties cleanly.

Round-trip support for VCard Extended (vendor defined) Properties. VCard itself already has some support for this (not tested currently), and the db schema already has a CONTACT_XTENDED table to store them. In theory, just need glue code in-between. I also cannot think of any particular reason Template needs to be altered, but a test case is probably needed.

Bigger issue is how to reflect on a VCard to figure out what VCard extended properties might be present. VCard DB would either need to iterate over all values to determine what is left that it doesn't know about (whereas now it is organized to methodically work through saving/retrieving what it does know about which I believe makes sense). The Template, likewise, would need to know that Extended values were there to output them (or to test for every conceivable value). Probably need some method on VCard to specifically iterate over JUST extended properties. Also may want a facility in Template to collect only those properties which have NOT been output and then have the ability to process just that bucket. This may require a separate issue, but the use case would be for the template writer to provide a bucket fragment for handling random un-handled properties, to for instance, write them as generic spans at the end of the vcard. Even being able to throw them out as marked hidden text would have diagnostic value, especially if one provides a template specifically for checking and logging potential problems with VCards in one's database (e.g. deprecated properties, unknown/unhandled properperties).

Allocate additional time to cleaning up/editing/improving the documentation post-VCard refactor. Incorporate diagrams of new object model and patterns involved.

After the refactoring of vcard-tools into VCardDB and a templating class ( #3 and #4), review PHP doc comments and make any necessary cleanup. Documentation should be updated as the refactoring proceeds, but this issue is to ensure that a pass is made to examine the documentation as a whole.

• Check and fix doc comments in vcard-tools.
• Update README.md as necessary to reflect the new organization.

Check and correct the names of the N property's sub-elements in the VCard class (e.g. 'FirstName' versus 'GivenName').

Require the ability to specify a language preference for templates when fetched from the registry and when fallback templates are evaluated.

Use Case

Application rendering pages in multiple languages. Application selects template from registry by name, in some way supplying a preferred language. Registry returns template, selecting from multiple templates of the same name according to the preferred language. When evaluating fallback templates, the same process is performed. If no language-specific template is available, a generic one is returned. This last allows the language-agnostic structural markup to be placed in the bottom-level template, overridden by language-specific catalogs at the top. Should consider language-hinting from the point-of-view of vcard-schema features as well: language and sort hinting should eventually affect selection of alternate vcard property representations and so forth according to these hints.

Suggested Interface

• Add a _template[language] property to the .INI files for templates and appropriate TemplateInfo changes to manipulate/retrieve.
• When registered, add a language code to the registration name.
• Implement a contextual object to set language/sort order preferences to use when retrieving/applying Templates.
• When retrieving templates, implement a search order to check for preferred templates and return the most appropriate template available.

Add any necessary tasks to the Ant build process to generate/update documentation of PHP code.

Allow update of properties in-place. Also support a copy-on-write flag for updating properties which are shared among multiple Contacts (requires #44 ).

Get code coverage analysis working in at least NetBeans, preferably stand-alone through Phing as well.

Currently, Netbeans has issue with some of my coverage annotations in the testcase--- probably best to strip them out and start over. Phing has issues with the autoloading (not finding same classes unit tests are loading).

This will be marked for the next cleanup milestone, but if doable sooner, I will move it up: I like having coverage reports as my unit tests develop and to ensure that tricky branches are being exercised as I go.

Find Contacts belonging to an organization by walking the tree of ORG (Property IDs) PIDs first. May also allow caller to request textual matching to locate ORGs which may not have been properly tagged by PIDs (or for which entries may have come from different sources).

Requires #44 .

Round-trip support for VCard 4.0 KEY property. Database table already exists.

The REV property notes a revision to a VCard. The UID is the primary key for the Contact and should remain the same (presumably) when the revision changes. Should explore an archive table to store
old revisions of a card if the app desires. Would need some utilities to fetch/store from the archive as well as to perform cleanup.

In order to be used in production, consistency of exception handling in VCardDB routines must be cleaned up. It is quite conceivable at the moment that exceptions thrown from \PDO calls, for instance, will leak resources when the stack is unrolled. Specifically:

• Ensure that exception-throwing routines are wrapped in try-catch-finally statements to ensure cleanup of resources (e.g. prepared statements).
• Re-throw exceptions as appropriate.
• Ensure that all re-thrown exceptions are declared appropriately in doc comments.

As mentioned in issue #11 , it makes sense to just convert the build script to use Phing instead of ant. Phing has built-in tasks for phpdoc, phpunit, and phar archive distribution and it will remove the dependencies on Java, Ant, and JDBC.

Require some reasonable approach for versioning the database schema, applying deltas and, if necessary, rolling them back.

Use Cases

In production:

• It is necessary to be able to adapt the schema and migrate data without the drop/recreate/reload that is easy at the unit-test stage.
• These changes should be tracked, describable, aggregatable, and recoverable:
• Create new database at any version level
• Migrate from any version level to any later version level
• Readily incorporate or work alongside check-pointing for catastrophic failure of applied change set
• In VCardTools development, we need to be able to understand the effect of DB changes on middle-ware code. Refactoring at one level can cross over into the boundaries of the other. We then need to describe those changes with the commit. This can often be facilitated by having smaller, packaged change-set deltas below the level of a git-check-in on a branch (following the principle of always checking in whole, functioning code as early and often as possible).
• In application development, it is necessary to track the relationship between VCard schema levels and the level being used in the developing application, to apply changes without (necessarily) destroying test data, etc.
• It would be nice if required db levels were trackable via Composer (#22) and that probably needs to be examined.

Deliverable

• Examine options, add further notes here and in wiki. Propose a strategy, opening additional Issues as necessary to implement. Code not required but controlled-experimentation is nice.

Options/Info

A couple of options and a tutorial:

• MigrateDB Java-based and Ant driven but apparently can be
  run under Phing.
• DBDeploy Also Java/Ant-based but can be run under Phing (old tutorial exists).

Considerations

Both of these tools would reintroduce a dependency on Java and JDBC. DBDeploy does not have a lot of recent activity, but as it appears relatively stable, that may not matter. If I recall correctly, both Oracle and DB/2 had some built-in utilities for change-sets/migration (might have used during IBM GS-Sprint/PCS project). I wouldn't bet that MySQL has any such facility, but it might be worth digging through docs of recent versions and verifying. At the very least, if I have notes from the project and can see how it was done for Sprint, that might better inform my choices. Also worth taking a look at e.g. Drupal, and seeing how their migrations are done.

Handle multiple URL properties as per spec.

At the moment, the default template is loaded relative to DIR and filenames for .ini files generally are not interpreted in any way. So, for instance, filenames for fallback templates embedded in .ini
files are not very robust. There should be some way to configure or control the template directory or
a search path for templates.

This issue may be best fixed by making TemplateRegistry a full class, allowing the user to configure the registry and, potentially, subclass it. I am imagining, particularly, that if one were using Template alongside vCardDB, one might want to store the templates for an application in the database and delay loading until a template is actually used. Allowing one to adapt the registry through polymorphism would make that more-or-less straight-forward and prevent me from trying to anticipate
everyone's needs.

VCard will be refactored to create Properties and Parameters as 1st-Class types using a Builder pattern to construct values. Goal is to build semantic structure into Properties to allow cleaner definition and manipulation of the different types of parameters (structured v. non-structured? do they take types? what parameters do they accept? single, multiple, or comma-separated sub-values? etc.). Should allow reflection for the caller to readily determine what values are acceptable, create and attach an acceptable structure for a given property, and extract information from a property.

Will be difficult to achieve an acceptable trade-off between complexity of object model and adequate representation of the variability of the VCard schema. Will not be able to model all of the RFC 6350 schema complexity, but should get the 90% that most applications (especially mine) will use and move from there.

Encapsulate the vcard-tools functions for HTML templating in a class, refactor appropriately, and demonstrate with unit tests.

Split the tests/TemplateTest class to put Substitution and TemplateInfo tests into separate files.

The query in filterIDsByKind(..) is constructed and therefore not easily removed to an .ini file (see #34).
Refactor the methods depending on this so that the select and filter can be done in one step from a
configured query. This should also be faster as the database can optimize the SELECTs and
perform all the steps internally.

There is no reason for these predicates (e.g. isKeySingleValueElement(..)) to be instance methods and they may sometimes need to be called in a static context (see mention in #27 and associated commit for isKeyTypeAble($key)).

Add appropriate triggers to db schema so that e.g. deletion of a contact will cascade to all subordinate records.

Encapsulate the various vcard-tools functions in a class, refactor appropriately, and improve unit tests on the way.

Refactor to extract the parsing and file import/export logic from VCard and place it in a separate class or classes. Will leverage the Property/Parameter classes developed for issue #35. Should be done with an eye toward future handling of multiple spec versions and may incorporate some legacy property handling (e.g. deprecated AGENT property) but mature support not a goal of this issue.

Check the README and other documentation to make sure they have been updated. Make any applicable changes.

Extract the SQL queries from the PHP source and load from external files (e.g.) .ini files. Intent is to allow easy external editing of SQL, and incorporate formatting not easy nested inside the PHP files. Will also begin to define an API layer between the SQL schema and the VCard class within the VCardDB utility.

Support the PID parameter and CLIENTPIDMAP property to control which property instances may be shared across vcards.

Move GEO Property to subsidiary table to support multiple values. Will also make code cleaner since then can be handled consistently with other structured properties.

Create a Phing task to make an appropriate distribution package. Probably should follow #22 . Do whatever is required to make the package available through Composer as well as create a phar archive for easy posting in GitHub.

Read and write Type parameters to/from database for structured elements (e.g. ADR). As these are already passed around as arrays, supporting Type should require minimal internal changes and that will provide a baseline for adding Type support for other elements.

As per #6 , handle ENCODING parameter on import by automatically decoding. Store internally in one encoding wherever remotely possible. Any situations where this not possible for some as-yet-unknown reason, handle as a special case. If appropriate, modify the database schema to conform to implementation choices. Enable proper encoding of blobs (DATA properties) in some reasonable and conformant fashion for export.

Add handling for the RELATED property as per RFC 6350 sec. 6.6.6. This may entail changes to VCard (allowed types), to VCardDB (to store and retrieve), and to templates (to output the parameter). It does not make any sense to do some of this before handling of the TYPE parameter is accomplished generally in VCardDB and in html templating.

Requires: #2

Need to examine the ENCODING issue and decide on an overall strategy for handling, creating sub-issues as necessary to carry out decisions.

Proposal

In theory, we can handle ENCODING at the parsing level and ignore it at the database level. Specifically, if encoded properties are decoded when property values are imported (from a raw vCard or some other source), then we can always encode the same way when storing to the database and always restore vCard fields with consistent encodings no matter how we got the data originally.

Need to write some testcases and prototype a small amount to identify any areas where we may actually want to preserve original encoding and how we want to handle the File-Type Properties specifically (e.g. LOGO, etc.). The existing vCard parsing does handle b64 encoding in some instances and I need to understand these blocks of code. This would probably be a very good start for some test cases.

Move N Property to a subsidiary table to support multiple values as per spec. At this point, this will make the code cleaner as well because it can be handled consistently with other structured properties. Will also make later internationalization changes possible. Carry changes through rest of system as necessary.

Allow Contacts to be updated in-place, properly handling properties shared between multiple Contacts. Requires #44 .

Figure out how to use composer for dependency management and integrate into the project. In particular, should be able to use its autoloader and have it manage phpunit. phpDocumentor versions and other dependencies. Tutorial at http://culttt.com/2014/03/12/build-php-package/ .

Look at performing column mapping on fetch in the SELECT statement instead of the two step process now implemented so that adding new types requires defining less arrays and the SQL will be easier to
move to .ini files or other external source.

According to RFC6350 6.7.6, UID should also be a single value element (zero or one occurrence).

Ensure round-trip support of JohnDoe.vcf card example (tests/vcards/) within the vCard class, demonstrated by unit tests. Properties/Parameters should be able to be:

• created within the interface
• read within the interface
• written to a file
• read from a file

More specific issues will be opened as individual testcases are written and fail.

Add handling for the vCard ANNIVERSARY property defined in RFC 6350 6.2.6. This may require changes in VCard, VCardDB, templates, and schema, as necessary.

Figure out how to use the GitHub Continuous Integration server to make tests automatically run on merges. Will have to follow #22 because the CI-server depends on Composer.

Now that everything is neatly in a namespace, set up class auto-loading so that we can remove the explicit requires.

Sharing properties between contacts via PID/CLIENTPIDMAP opens up the possibility that properties may be left behind due to update/delete/copy-on-write operations. Need to either:

1. Add appropriate triggers to make sure that this occurs on update/delete (ON UPDATE CASCADE/ON DELETE CASCADE will not do so by itself when a link-table and potentially multiple grouped properties are involved) or

2. Provide utilities to identify such records and let the application determine how to deal with them. The application might wish to leave some orphaned properties in place. For example, a user might have multiple addresses defined as snippets for constructing VCards which might not be used in a specific VCard at a specific moment (especially if the snippet is created first, then the VCard it is used in). Consider on-line payment applications with billing addresses which may or may not be associated with a specific credit card at a specific moment. As a compromise,

3. Add triggers to index potentially problem entries in a subsidiary table on occurrence and provide some utilities to deal with them under application control. This can then readily lead to the application configuring automatic behavior, batch processing orphans during a maintenance cycle (nightly CRON or whatever) or flagging them for interactive maintenance.

Consider but do not worry overly about access control: a user may updated/delete one record which may affect records they do not have permissions to access. Such behavior is completely within the sphere of the end application and there is no reason to try to deal with it, but we don't want to unnecessarily complicate application ACLs.

VCardDB has to know what fields may be present in structured properties in order to properly bind
parameters. This data is duplicated in VCardDB because the appropriate structures in VCard are
private. Provide an API to expose this data in VCard and remove from VCardDB.

Define a namespace for the various classes in VCARD Tools.

Add code to VCardDB to delete a contact from the database. Requires #14.

In the VCard standard, the address property is ADR, but in the database schema, it is MAILING_ADDRESS. And yet, the email property is EMAIL in both (not EMAIL_ADDRESS). This makes for easy mistakes in writing SQL and moving data between the schema and the VCard class elements. It also complicates code where a simple loop-and-assignment across columns returned in a row requires additionally translating column names to VCard properties.

It is probably best to make these changes early on, before the tools are used in many projects.

Change all method names to camelCase to conform to PSR-1. The only place this should be an issue is in my convention of using an i_ to denote internal (private) methods. As I find that this reduces mistakes (especially where there is a similar public/non-public method), I am not going to eliminate the practice, but renaming them with an initial i (no underscore) might work, and, as they are private methods, they won't effect any calling code.