The Phorge codebase has lot of entries like this one:

$file = something
// Generate an image transformation, usually smaller (orphan now).
$xform_key = PhabricatorFileThumbnailTransform::TRANSFORM_WORKCARD;
$xform = PhabricatorFileTransform::getTransformByKey($xform_key)
  ->executeTransform($file);

The issue is, this generate a transform that is orphan. That is, without persisting any PhabricatorTransformedFile relationship.

As workaround, in a pair of occasions, we expanded the above block with the following piece of code:

// Make that image transformation non-orphan.
id(new PhabricatorTransformedFile())
  ->setOriginalPHID($file_phid)
  ->setTransformedPHID($xform->getPHID())
  ->setTransform($xform_key)
  ->save();

But probably, this should be somehow less "manual". If not, automatic.

Proposal n. 1 - a new executeTransform "explicit" (or similar)

Let's improve PhabricatorFileTransform to have a new commodity method that executes the transform and also persists the PhabricatorTransformedFile.

Pros:

• easy: we just introduce a new method
• stable: we may have not a complete overview of the current usages, so it's probably nice to introduce something new and slowly adopt that when needed

Cons:

• we should probably proactively look at all calls of executeTransform and replace these to executeTransformExplicit or whatever.
• in one year we may end in discovering that all usages actually were needing this

Proposal n. 2 - changing executeTransform itself

Pros:

• easy: we just introduce a new method
• stable: we may have not a complete overview of the current usages, so it's probably nice to introduce something new and slowly adopt that when needed

Cons:

• risky, we don't have a complete big picture of all usages of executeTransform