feat: improve errors by hoisting ErrorInfo fields directly in error message

[alicejli]

As part of the overall GAPIC Error Details Improvements project, this feature improves the usability of the error information by including three additional fields (if available) directly in the error itself e.g. ErrorInfo that offer more detailed information for troubleshooting. These three fields are domain, reason, and metadata.

This PR also includes getters for those fields so users may access them directly.

This PR is dependent on googleapis/common-protos-php#27 being merged which will not happen until post-freeze, sometime in January.

Please ping me for internal docs if desired.

Current REST sample error:

PHP Fatal error:  Uncaught Google\ApiCore\ApiException: {
    "message": "Cloud Translation API has not been used in project <id> before or it is disabled. Enable it by visiting https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id> then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "code": 7,
    "status": "PERMISSION_DENIED",
    "details": [
        {
            "@type": "type.googleapis.com\/google.rpc.Help",
            "links": [
                {
                    "description": "Google developers console API activation",
                    "url": "https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id>"
                }
            ]
        },
        {
            "@type": "type.googleapis.com\/google.rpc.ErrorInfo",
            "reason": "SERVICE_DISABLED",
            "domain": "googleapis.com",
            "metadata": {
                "consumer": "projects\/<id>",
                "service": "translate.googleapis.com"
            }
        }
    ]
}

With this change, REST sample error:

Google\ApiCore\ApiException: {
    "message": "Cloud Translation API has not been used in project <id> before or it is disabled. Enable it by visiting https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id> then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "domain": "googleapis.com",
    "reason": "SERVICE_DISABLED",
    "errorInfoMetadata": {
        "consumer": "projects\/<id>",
        "service": "translate.googleapis.com"
    },
    "code": 7,
    "status": "PERMISSION_DENIED",
    "details": [
        {
            "@type": "type.googleapis.com\/google.rpc.Help",
            "links": [
                {
                    "description": "Google developers console API activation",
                    "url": "https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id>"
                }
            ]
        },
        {
            "@type": "type.googleapis.com\/google.rpc.ErrorInfo",
            "reason": "SERVICE_DISABLED",
            "domain": "googleapis.com",
            "metadata": {
                "consumer": "projects\/<id>",
                "service": "translate.googleapis.com"
            }
        }
    ]
}

Current GRPC sample error:

Google\ApiCore\ApiException: {
    "message": "Cloud Translation API has not been used in project <id> before or it is disabled. Enable it by visiting https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id> then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "code": 7,
    "status": "PERMISSION_DENIED",
    "details": [
        {
            "@type": "google.rpc.errorinfo-bin",
            "data": "<Unknown Binary Data>"
            }
        },
        {
            "@type": "google.rpc.help-bin",
            "links": [
                {
                    "description": "Google developers console API activation",
                    "url": "https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id>"
                }
            ]
        },
        {
            "@type": "grpc-status-details-bin",
            "data": "<Unknown Binary Data>"
        },
        {
            "@type": "grpc-server-stats-bin",
            "data": "<Unknown Binary Data>"
        }
    ]
}

With this change, GRPC sample error:

Google\ApiCore\ApiException: {
    "message": "Cloud Translation API has not been used in project <id> before or it is disabled. Enable it by visiting https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id> then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "domain": "googleapis.com",
    "reason": "SERVICE_DISABLED",
    "errorInfoMetadata": {
        "service": "translate.googleapis.com",
        "consumer": "projects\/<id>"
    },
    "code": 7,
    "status": "PERMISSION_DENIED",
    "details": [
        {
            "@type": "google.rpc.errorinfo-bin",
            "reason": "SERVICE_DISABLED",
            "domain": "googleapis.com",
            "metadata": {
                "service": "translate.googleapis.com",
                "consumer": "projects\/<id>"
            }
        },
        {
            "@type": "google.rpc.help-bin",
            "links": [
                {
                    "description": "Google developers console API activation",
                    "url": "https:\/\/console.developers.google.com\/apis\/api\/translate.googleapis.com\/overview?project=<id>"
                }
            ]
        },
        {
            "@type": "grpc-status-details-bin",
            "data": "<Unknown Binary Data>"
        },
        {
            "@type": "grpc-server-stats-bin",
            "data": "<Unknown Binary Data>"
        }
    ]
}

[alicejli]

Requesting @noahdietz , @bshaffer as PHP owners, and @summer-ji-eng as Error Improvement project lead for review.
Tests will fail until googleapis/common-protos-php#27 is merged.

This is a non urgent review as we will not be able to release this until post freeze. Thanks!

[noahdietz]

A few comments to start. Can you also run the php formatting tool? Should be in the readme somewhere.

[noahdietz]

Can you add php doc comments to all of the added public APIs?

[summer-ji-eng]

Does this implementation cover for REST mode?

[alicejli]

Does this implementation cover for REST mode?

Yup! I added a test for the error info in REST response. Good catch.

[noahdietz]

LGTM! Great stuff Alice. I will let @bshaffer review/Approve.

[summer-ji-eng]

Thanks Alice for your work. LGTM.
Not blocker, but please add the integration test for grpc and rest.

[bshaffer]

Some suggestions for cleanup, otherwise looks great