Entities Exploration
Preliminary questions:
- How does it work the PhabricatorDestructibleInterface?
- How does a destroyObjectPermanently(PhabricatorDestructionEngine $engine) should work?
Exploration:
This interface
| Entity | Has Child-Entity? | Has PhabricatorDestructibleInterface? | What does it call? | and is it wrapped in transaction? |
|---|---|---|---|---|
| ManiphestTask | No? (fields) | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | ✅ ..inside openTransaction() |
| PonderQuestion | Yes | Yes. Has destroyObjectPermanently() | ..that calls $engine->destroyObject(PonderAnswer) and $this->delete() | ✅ ..inside openTransaction() |
| - PonderAnswer | No | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | ✅ ..inside openTransaction() |
| PhabricatorDashboard | No? | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | 🙅 .. without openTransaction() |
| PhabricatorDashboardPanel | Yes? | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | ✅ ..inside openTransaction() |
| PhameBlog | Yes | Yes. Has destroyObjectPermanently() | ..that calls $engine->destroyObject(PhamePost) and $this->delete() | ✅ ..inside openTransaction() |
| - PhamePost | No (comments?) | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | ✅ ..inside openTransaction() |
| PhrictionContent | No (comments?) | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | 🙅 .. without openTransaction() |
| PhabricatorAuthPassword | No | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | 🙅 .. without openTransaction() |
| HeraldRule | Yes (conditions?) | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | ✅ ..inside openTransaction() |
| - HeraldCondition | No | No. | ||
| -- HeraldActionRecord | No | No. | ||
| HeraldTranscript | Yes | Yes. Has destroyObjectPermanently() | ..that calls $this->delete() | ✅ ..inside openTransaction() |
| - HeraldConditionTranscript | Yes (results) | No. | ||
| -- HeraldTranscriptResult | No? | No. | ||
Notes:
- * = Has Child-Entities? If it has children-entities that cannot live alone without this parent.
Destruction Engines Exploration
Preliminary questions:
- How does it work a DestructionEngineExtension (compared with the above?)
- Who fires it?
Exploration:
Destruction Engines are engines that take "generic input objects" and destroy "related specific related entities".
For example, if you drop a Maniphest Task, its Herald Transcripts may be deleted thanks to the HeraldTranscriptDestructionEngineExtension.
These Destruction Engines are supposed to be executed in the background by phd after you destroy a generic object.
| Destruction Engine | What does it call? | and is it wrapped in transaction? |
|---|---|---|
| HeraldTranscriptDestructionEngineExtension | calls $engine->destroyObject(HeraldTranscript) | 🙅 .. without openTransaction() |
| PhabricatorPasswordDestructionEngineExtension | calls $engine->destroyObject(PhabricatorAuthPassword) | 🙅 .. without openTransaction() |
| PhabricatorTokenDestructionEngineExtension | calls PhabricatorTokenGiven#delete() | 🙅 .. without openTransaction() |
| PhabricatorMailPropertiesDestructionEngineExtension | calls PhabricatorMetaMTAMailProperties#delete() | 🙅 .. without openTransaction() |
| PhabricatorWorkerDestructionEngineExtension | calls PhabricatorWorkerActiveTask#archiveTask() | 🙅 .. without openTransaction() |
| PhabricatorNotificationDestructionEngineExtension | runs DELETE query | 🙅 .. without openTransaction() |
| PhabricatorSearchIndexVersionDestructionEngineExtension | runs DELETE query | 🙅 .. without openTransaction() |
| PhabricatorSearchNgramsDestructionEngineExtension | runs DELETE query | 🙅 .. without openTransaction() |
Thanks for adding details.
Post Considerations
In short:
| $engine->destroyObject(SOMETHING) | This is useful to cause a cascade deletion of "related things". So if you drop a Task, you also drop Herald transcripts, Flags, etc. |
| SOMETHING->delete() | It has sense for minimal entities that has no Herald transcripts, flags, etc. |
About T15110: File reference not removed when file is deleted: how to destroy PhabricatorFileAttachment correctly?
From the perspective of its parent class File:
- PhabricatorFile has the child-entity PhabricatorFileAttachment that cannot live without a File
- 💚 → if we want to act like PonderQuestion and PhameBlog and PhabricatorAuthPassword etc.
- 🔶 → so, it MAY have sense to call $engine->destroyObject(PhabricatorFileAttachment) and $this->delete() ..inside openTransaction()
- → so PhabricatorFileAttachment should have a PhabricatorDestructibleInterface
- → it can just behave like PhamePost and runs just $this->delete() ..inside openTransaction()
- → so PhabricatorFileAttachment should have a PhabricatorDestructibleInterface
- 🔴 but it's probably overkill, since the attachment is NOT like a PonderAnswer or a PhamePost - for example, the attachment cannot have flags. So we can just call PhabricatorFileAttachment#delete()
- 🔶 → so, it MAY have sense to call $engine->destroyObject(PhabricatorFileAttachment) and $this->delete() ..inside openTransaction()
- 💚 → if we want to act like PonderQuestion and PhameBlog and PhabricatorAuthPassword etc.
- it should exist a destruction engine to delete orphan PhabricatorFileAttachment - hypothetical PhabricatorFileAttachmentDestructionEngineExtension
- 🔴🔴🔴🔴 → UNCLEAR whenever we should use $engine->destroyObject(PhabricatorFileAttachment) or just PhabricatorFileAttachment#delete()
- per above, probably just delete()
- 🔴🔴🔴🔴 → UNCLEAR whenever we should use $engine->destroyObject(PhabricatorFileAttachment) or just PhabricatorFileAttachment#delete()
Thanks for any comment 🌈