Converting between versions¶
Gedcom::convert() converts a document to another version and returns the new document, its
output and a loss report. The input is not changed.
use Korin\Gedcom\Gedcom;
use Korin\Gedcom\Version;
$doc = Gedcom::read('family.ged'); // 5.5.1
$result = Gedcom::convert($doc, Version::V7_0);
file_put_contents('family-7.ged', $result->output()); // in the encoding of the version
$seven = $result->document(); // to edit further
echo count($result->losses()), ' losses', PHP_EOL;
Any of 5.5, 5.5.1, 5.5.5 and 7.0 converts to any other, through the versions between them. GEDCOM 4.0 and the 5.0–5.4 drafts convert from, not to. The output is UTF-8, or UTF-16 for 5.5, which has no UTF-8.
Losses¶
What the target version cannot hold is kept as an extension tag and reported: nothing is dropped
without a report, so a file can be converted, edited and converted back. Each loss has a stable
KL* code, the path and line it comes from, and how it was stored.
use Korin\Gedcom\Model\Sex;
use Korin\Gedcom\Syntax\Document;
$tree = Document::create(Version::V7_0);
$tree->addIndividual()->setSex(Sex::Intersex);
$result = Gedcom::convert($tree, Version::V5_5_1);
foreach ($result->losses() as $loss) {
echo $loss, PHP_EOL; // KL3002 warning (@I1@/SEX), extension: SEX X has no 5.5.1 value: SEX U
}
echo json_encode($result->losses()), PHP_EOL; // {"from":"7.0","to":"5.5.1","entries":[…]}
The output holds 1 SEX U with 2 _SEX X under it. Converting it back to 7.0 restores SEX X.
Policies¶
use Korin\Gedcom\ConvertOptions;
use Korin\Gedcom\Conversion\LossPolicy;
use Korin\Gedcom\Exception\ConversionException;
$dropped = Gedcom::convert($tree, Version::V5_5_1, (new ConvertOptions())->withPolicy(LossPolicy::DropWithReport));
try {
Gedcom::convert($tree, Version::V5_5_1, (new ConvertOptions())->withPolicy(LossPolicy::Fail));
} catch (ConversionException $e) {
echo $e->getMessage(), PHP_EOL; // Conversion stopped by a loss: KL3002 …
}
| Policy | What is lost |
|---|---|
PreserveAsExtension (default) |
Kept as an extension tag, reported |
DropWithReport |
Dropped, reported |
Fail |
ConversionException at the first loss |
Lines that are not GEDCOM lines are dropped under every policy (KL1001).
Files of any size¶
Gedcom::convertFile() converts record by record without reading the whole file, with the
output and losses of convert():
$losses = Gedcom::convertFile('family.ged', 'family-7.ged', Version::V7_0);
The rules of each pair of versions are in Conversion rules; every loss code is in Losses.